{"id":27954385,"url":"https://github.com/ebu/cpa-ios","last_synced_at":"2025-06-11T08:36:16.787Z","repository":{"id":30103735,"uuid":"33653508","full_name":"ebu/cpa-ios","owner":"ebu","description":"iOS library for the Cross-Platform Authentication Protocol (ETSI TS 103 407)","archived":false,"fork":false,"pushed_at":"2016-04-15T14:17:52.000Z","size":467,"stargazers_count":4,"open_issues_count":8,"forks_count":1,"subscribers_count":14,"default_branch":"develop","last_synced_at":"2025-05-07T17:28:27.748Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://tech.ebu.ch/cpa","language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ebu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-09T06:55:41.000Z","updated_at":"2016-04-15T14:31:07.000Z","dependencies_parsed_at":"2022-08-26T09:31:45.585Z","dependency_job_id":null,"html_url":"https://github.com/ebu/cpa-ios","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebu%2Fcpa-ios","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebu%2Fcpa-ios/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebu%2Fcpa-ios/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebu%2Fcpa-ios/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ebu","download_url":"https://codeload.github.com/ebu/cpa-ios/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebu%2Fcpa-ios/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259230679,"owners_count":22825438,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-07T17:27:21.190Z","updated_at":"2025-06-11T08:36:16.776Z","avatar_url":"https://github.com/ebu.png","language":"Objective-C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cross-Platform Authentication - iOS Client\n\n[![Build Status](https://img.shields.io/travis/ebu/cpa-ios/develop.svg?style=flat)](https://travis-ci.org/ebu/cpa-ios)\n[![Platform](https://img.shields.io/cocoapods/p/cpa-ios.svg?style=flat)](http://cocoadocs.org/docsets/cpa-ios/)\n[![Pod Version](https://img.shields.io/cocoapods/v/cpa-ios.svg?style=flat)](http://cocoadocs.org/docsets/cpa-ios/)\n[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)\n[![License](https://img.shields.io/cocoapods/l/cpa-ios.svg?style=flat)](LICENSE)\n\nThe Cross-platform Authentication (CPA) protocol provides a common formalism between device manufacturers and content providers to offer personalized services to their audience. It makes it possible for a user to conveniently access these services as a single identity accross devices and applications.\n\nThis software implements version 1.0 of the Cross-Platform Authentication Protocol ([ETSI TS 103 407](https://portal.etsi.org/webapp/WorkProgram/Report_WorkItem.asp?WKI_ID=47970)).\n\nMore information is available on the [EBU Cross-Platform Authentication project page](http://tech.ebu.ch/cpa).\n\n## Compatibility\n\nThe CPA iOS library requires the most recent versions of Xcode and of the iOS SDK, currently:\n\n* Xcode 7.2\n* iOS 9.2 SDK\n\nDeployment is supported for the two most recent major iOS versions, currently:\n\n* iOS 8.x\n* iOS 9.x\n\nAll architectures are supported:\n\n* i386 and x86_64\n* armv7, armv7s and arm64\n\nThe CPA iOS library can be used both from Objective-C or Swift files. It does not contain any private API method calls and is therefore App Store compliant.\n\n## Getting started\n\nThe library can be added to a project with [CocoaPods](http://cocoapods.org/) or [Carthage](https://github.com/Carthage/Carthage).\n\n### Installation with CocoaPods\n\nAdd `CrossPlatformAuthentication` as dependency in your `Podfile`:\n\n```ruby\npod 'CrossPlatformAuthentication', '\u003cversion\u003e'\n```\n\nThen run `pod install` to update the dependencies. You can also add the `use_frameworks!` directive in your `Podfile`, which embeds the library as a native Cocoa Touch framework.\n\nFor more information about CocoaPods and the `Podfile`, please refer to the [official documentation](http://guides.cocoapods.org/).\n\n### Installation with Carthage\n\nYou can use the library as an embedded Cocoa Touch framework, conveniently managed using Carthage. \n\nAdd `cpa-ios` as dependency in your `Cartfile`:\n\n```\ngithub \"ebu/cpa-ios\" == \u003cversion\u003e\n```\n\nThen run `carthage update` to update the dependencies. Unlike CocoaPods, your project is not changed. You will need to manually add the `CrossPlatformAuthentication.framework` generated in the `Carthage/Build/iOS` folder to your projet. Refer to the [official documentation](https://github.com/Carthage/Carthage) for more information.\n\n### Usage\n\nA global `CrossPlatformAuthentication .h` header file is provided. You can of course individually import public header files if you prefer, though.\n\n#### Usage from Objective-C source files\n\nImport the global header file using\n\n```objective-c\n#import \u003cCrossPlatformAuthentication/CrossPlatformAuthentication.h\u003e\n```\n\nYou can similarly import individual files, e.g.\n\n```objective-c\n#import \u003cCrossPlatformAuthentication/CAPProvider.h\u003e\n```\n\nIf you use Carthage or CocoaPods with the `use_frameworks!` directive, it is easier to import the `CrossPlatformAuthentication` module itself where needed:\n\n```objective-c\n@import CrossPlatformAuthentication;\n```\n\n#### Usage from Swift source files\n\nIf you installed the library with CocoaPods but without the `use_frameworks!` directive, import the global header from a bridging header:\n\n```objective-c\n#import \u003cCrossPlatformAuthentication/CrossPlatformAuthentication.h\u003e\n```\n\nIf you use Carthage or CocoaPods with the `use_frameworks!` directive, it is easier to import the library module where needed instead:\n\n```swift\nimport CrossPlatformAuthentication\n```\n\n### Concepts\n\nA brief overview of the main CPA iOS library concepts is provided below. For more information about CPA itself, please refer to the [EBU Tech 3366 specification document](https://tech.ebu.ch/docs/tech/tech3366.pdf).\n\n#### Authorization provider\n\nThe most important class you will use is `CPAProvider`, which manages authentication with a single authorization provider (AP). APs are authorities responsible for the delivery of tokens, in general for several service providers corresponding to various domains. Most applications should only require a single `CPAProvider` instance, which you can install as default instance for convenient application-wide access:\n\n```objective-c\nCPAProvider *provider = [[CPAProvider alloc] initWithAuthorizationProviderURL:providerURL];\n[CPAProvider setDefaultProvider:provider];\n```\n\nand easily retrieve when needed:\n\n```objective-c\nCPAProvider *defaultProvier = [CPAProvider defaultProvider];\n```\n\n#### Tokens\n\nAPs can deliver two kinds of tokens for domains:\n\n* Client tokens, associated with an anonymous identity. This anonymous identity is meant for _out of the box_ experience without requiring immediate registration with a user account\n* User token, associated with an account\n\nTo request a token, simply call the dedicated `CPAProvider` method. If you have set a default provider as described above, this boils down to:\n\n```objective-c\n[[CPAProvider defaultProvider] requestTokenForDomain:@\"cpa.mydomain.com\" withType:type completionBlock:^(CPAToken *token, NSError *error) {\n    if (error) {\n        // Deal with the error\n    }\n    else {\n      // Use the received token\n    }\n}];\n```\n\nwhere type is either `CPATokenTypeClient` or `CPATokenTypeUser` for client, respectively user tokens. The domain must be a host name, `cpa.mydomain.com` in the example above, optionally followed by a port number. Tokens received for a domain are valid for all endpoints related to this domain, e.g. `https://cpa.mydomain.com/playlist` or `https://cpa.mydomain.com/hbbtv`.\n\nA token received for a domain is automatically stored within the keychain, and can simply be retrieved without performing a request to the AP:\n\n```objective-c\nCPAToken *token = [[CPAProvider defaultProvider] tokenForDomain:@\"cpa.mydomain.com\"];\nif (token) {\n    // Use the token\n}\n```\n\nTokens might expire, though. If the service provider hapens to reject an associated token available from the keychain, request another token using the same method as above.\n\n#### User tokens and supplying credentials\n\nWhen requesting a user token for a domain, the AP will in general require the user to supply her credentials. These are entered using a web page displayed by an in-app web browser (though it would have been better to use Safari instead of a built in solution, Apple has a history of rejecting applications using Safari for this purpose).\n\nAn AP might provide single sign-on for several domains. In such cases, provided a user already obtained a user token for a domain, she might obtain a token for an affiliated domain without the need to supply her credentials again.\n\nBy default, the in-app browser is presented modally. This might not always suit your needs, in which case you can supply an additional presentation block when rquesting the token. For example, to present the browser in a navigation controller:\n\n```objective-c\n[[CPAProvider defaultProvider] requestTokenForDomain:domain withType:type credentialsPresentationBlock:^(UIViewController *viewController, CPAPresentationAction action) {\n    if (action == CPAPresentationActionShow) {\n        [navigationController pushViewController:viewController animated:YES];\n    }\n    else {\n        [navigationController popViewControllerAnimated:YES];\n    }\n} completionBlock:^(CPAToken *token, NSError *error) {\n    if (error) {\n        // Deal with the error\n    }\n    else {\n        // Use the received token\n    }\n}];\n```\n\n#### Token group sharing\n\nTokens can be shared between applications from the same group:\n\n* Create an application group on the developer portal, and associate it with each application. For more information, please refer to the [official documentation](https://developer.apple.com/library/ios/documentation/General/Conceptual/ExtensibilityPG/ExtensionScenarios.html)\n* Provide the group identifier when instantiating the `CPAProvider`:\n\n    ```objective-c\n    CPAProvider *provider = [[CPAProvider alloc] initWithAuthorizationProviderURL:providerURL\n                                                              keyChainAccessGroup:@\"group.mygroup.identifier\"];\n    ```\n    \nFor this provider, tokens will now be saved and retrieved for the application group as a whole.\n\n## Demo project\n\nA demo project is available, just build `cpa-ios-demo` (Objective-C implementation) or `cpa-ios-demo-swift` (Swift implementation).\n\nThe application provides a way to retrieve tokens for two different services (playlist and HbbTV) from a common AP. A third dummy domain, for which the AP cannot deliver tokens, can be selected as well.\n\nWhen requesting a token for a domain, you can:\n\n* Ask for an authenticated (user) or unauthenticated (client) token\n* Force token renewal to avoid using a token already available from the keychain\n* Use a custom transition when displaying the in-app browser (navigation controller push and pop instead of modal presentation)\n\nClicking on the _Retrieve token_ button retrieves a token and display it below.\n\nThe two playlist and HbbTV services should provide single sign-on. This means that if you obtain a user token for one of them, you can obtain a user token for the other one without the need to supply your credentials again.\n\n## Contributing\n\nYou can contribute to the project using pull requests. Simply checkout the project and update CocoaPods dependencies by running:\n\n```\n$ pod install\n```\n\nfrom the main project directory.\n\nAn `install_git_hooks.sh` script is available from the main directory. You should run it once to install convenient git hooks which take care of properly assigning Travis CI badges on a branch basis.\n\n### Code coverage\n\nTo get code coverage results locally, proceed as follows:\n\n* Clone XcodeCoverage somewhere:\n\n    ```\n    $ git clone git@github.com:jonreid/XcodeCoverage.git\n    ```\n    \n* Switch to the `cpa-ios` subdirectory and create a symbolic link to your XcodeCoverage working copy:\n\n    ```\n    $ cd cpa-ios\n    $ ln -s /path/to/XcodeCoverage\n    ```\n\n* Run the tests within Xcode by switching to the `cpa-ios-tests-runner` target and pressing ⌘+U\n* Generate the code coverage report by running the `getcov` command:\n\n    ```\n    $ cd cpa-ios\n    $ ./XcodeCoverage/getcov -s\n    ```\n    \nYour default browser should open and display the coverage results.\n\n\n## Related projects\n\n* [Tutorial](https://github.com/ebu/cpa-tutorial)\n* [Authentication Provider](https://github.com/ebu/cpa-auth-provider)\n* [Service Provider](https://github.com/ebu/cpa-service-provider)\n* [Android Client](https://github.com/ebu/cpa-android)\n* [JavaScript Client](https://github.com/ebu/cpa.js)\n\n\n## Contributors\n\n* [Samuel Défago](https://github.com/defagos) (RTS)\n* [Michael Barroco](https://github.com/barroco) (EBU)\n\n## Copyright \u0026 license\n\nCopyright (c) 2015-2016, EBU-UER Technology \u0026 Innovation\n\nThe code is under BSD (3-Clause) License. (see LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Febu%2Fcpa-ios","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Febu%2Fcpa-ios","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Febu%2Fcpa-ios/lists"}