diff --git a/README.md b/README.md index 3e7f82e642c..1295f4e4133 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,9 @@ > This is a new version of this SDK, the new pod name is [OktaOidc](https://cocoapods.org/pods/OktaOidc). The old [OktaAuth](https://cocoapods.org/pods/OktaAuth) pod is now deprecated. -This library is a swift wrapper around the [AppAuth-iOS](https://github.com/openid/AppAuth-iOS) objective-c code for communicating with Okta as an OAuth 2.0 + OpenID Connect provider, and follows current best practice for native apps using [Authorization Code Flow + PKCE](https://developer.okta.com/authentication-guide/implementing-authentication/auth-code-pkce). +This library is a Swift wrapper around the [AppAuth-iOS](https://github.com/openid/AppAuth-iOS) Objective-C code for communicating with Okta as an OAuth 2.0 + OpenID Connect provider, and follows current best practice for native apps using [Authorization Code Flow + PKCE](https://developer.okta.com/authentication-guide/implementing-authentication/auth-code-pkce). -You can learn more on the [Okta + iOS](https://developer.okta.com/code/ios/) page in our documentation. You can also download our [sample application](https://github.com/okta/samples-ios/tree/master/browser-sign-in) +You can learn more on the [Okta + iOS](https://developer.okta.com/code/ios/) page in our documentation. You can also download our [sample application](https://github.com/okta/samples-ios/tree/master/browser-sign-in). **Table of Contents** @@ -41,6 +41,7 @@ You can learn more on the [Okta + iOS](https://developer.okta.com/code/ios/) pag - [Running Tests](#running-tests) - [Modify network requests](#modify-network-requests) - [Known issues](#known-issues) +- [Contributing](#contributing) @@ -53,13 +54,15 @@ You'll also need: - An Okta account, called an _organization_ (sign up for a free [developer organization](https://developer.okta.com/signup/) if you need one). - An Okta Application, configured as a Native App. This is done from the Okta Developer Console and you can find instructions [here](https://developer.okta.com/authentication-guide/implementing-authentication/auth-code-pkce). When following the wizard, use the default properties. They are designed to work with our sample applications. +**Note:** If you would like to use your own in-app user interface instead of the web browser, you can do so by using our [Swift Authentication SDK](https://github.com/okta/okta-auth-swift). + ## Supported Platforms ### iOS Okta OIDC supports iOS 11 and above. ### macOS -Okta OIDC supports macOS (OS X) 10.10 and above. Library supports both custom schemes; a loopback HTTP redirects via a small embedded server. +Okta OIDC supports macOS (OS X) 10.14 and above. Library supports both custom schemes; a loopback HTTP redirects via a small embedded server. ## Install @@ -93,6 +96,12 @@ To integrate this SDK into your Xcode project using [Carthage](https://github.co github "okta/okta-oidc-ios" ``` +Then install it into your project: + +`carthage update --use-xcframeworks` + +**Note:** Make sure Carthage version is 0.37.0 or higher. Otherwise, Carthage can fail. + ## Usage Guide For an overview of this library's features and authentication flows, check out [our developer docs](https://developer.okta.com/code/ios). @@ -151,7 +160,7 @@ The easiest way is to create a property list in your application's bundle. By de ### Configuration object -Alternatively, you can create a configuration object ( `OktaOidcConfig`) from dictionary with the required values: +Alternatively, you can create a configuration object (`OktaOidcConfig`) from dictionary with the required values: ```swift let configuration = OktaOidcConfig(with: [ @@ -205,7 +214,7 @@ oktaOidc.signInWithBrowser(from: viewController, additionalParameters: ["idp": " // stateManager.refreshToken } ``` -Sample app [example](https://github.com/okta/samples-ios/blob/master/browser-sign-in/OktaBrowserSignIn/WelcomeViewController.swift#L35-L46) +Sample app [example](https://github.com/okta/samples-ios/blob/master/browser-sign-in/OktaBrowserSignIn/WelcomeViewController.swift#L35-L46). #### macOS ```swift @@ -240,7 +249,7 @@ oktaOidc.signOutOfOkta(authStateManager, from: viewController) { error in } } ``` -Sample app [example](https://github.com/okta/samples-ios/blob/master/browser-sign-in/OktaBrowserSignIn/SignInViewController.swift#L62-L74) +Sample app [example](https://github.com/okta/samples-ios/blob/master/browser-sign-in/OktaBrowserSignIn/SignInViewController.swift#L62-L74). #### macOS ```swift @@ -260,12 +269,12 @@ oktaOidc.signOutOfOkta(authStateManager: authStateManager, redirectServerConfigu This method helps to perform a multi-step sign-out flow. The method provides options that you want to perform and the SDK runs the options as a batch. The available options are: -- revokeAccessToken - SDK revokes access token -- revokeRefreshToken - SDK revokes refresh token -- removeTokensFromStorage - SDK removes tokens from the secure storage -- signOutFromOkta - SDK calls [`signOutOfOkta`](#signoutofokta) -- revokeTokensOptions - revokes access and refresh tokens -- allOptions - revokes tokens, signs out from Okta, and removes tokens from the secure storage +- `revokeAccessToken` - SDK revokes access token +- `revokeRefreshToken` - SDK revokes refresh token +- `removeTokensFromStorage` - SDK removes tokens from the secure storage +- `signOutFromOkta` - SDK calls [`signOutOfOkta`](#signoutofokta) +- `revokeTokensOptions` - revokes access and refresh tokens +- `allOptions` - revokes tokens, signs out from Okta, and removes tokens from the secure storage The order of operations performed by the SDK: 1. Revoke the access token, if the option is set. If this step fails step 3 will be omitted. @@ -333,7 +342,7 @@ oktaOidc.authenticate(withSessionToken: token) { stateManager, error in // stateManager.refreshToken } ``` -Sample app [example](https://github.com/okta/samples-ios/blob/master/custom-sign-in/OktaNativeLogin/UserProfile/UserProfileViewController.swift#L39-L50) +Sample app [example](https://github.com/okta/samples-ios/blob/master/custom-sign-in/OktaNativeLogin/UserProfile/UserProfileViewController.swift#L39-L50). ### stateManager @@ -352,9 +361,9 @@ oktaOidc.signInWithBrowser(from: self) { stateManager, error in stateManager.writeToSecureStorage() } ``` -Sample app [example](https://github.com/okta/samples-ios/blob/master/browser-sign-in/OktaBrowserSignIn/WelcomeViewController.swift#L44) +Sample app [example](https://github.com/okta/samples-ios/blob/master/browser-sign-in/OktaBrowserSignIn/WelcomeViewController.swift#L44). -To retrieve stored manager call `readFromSecureStorage(for: )` and pass here Okta configuration that corresponds to a manager you are interested in. +To retrieve stored manager call `readFromSecureStorage(for:)` and pass here Okta configuration that corresponds to a manager you are interested in. ```swift guard let stateManager = OktaOidcStateManager.readFromSecureStorage(for: oktaConfig) else { @@ -366,7 +375,7 @@ guard let stateManager = OktaOidcStateManager.readFromSecureStorage(for: oktaCon // stateManager.idToken // stateManager.refreshToken ``` -Sample app [example](https://github.com/okta/samples-ios/blob/master/browser-sign-in/OktaBrowserSignIn/AppDelegate.swift#L32) +Sample app [example](https://github.com/okta/samples-ios/blob/master/browser-sign-in/OktaBrowserSignIn/AppDelegate.swift#L32). **Note:** In OktaOidc SDK 3.0 we added support for multiple Oauth 2.0 accounts. So developer can use Okta endpoint, social endpoint and others in one application. Therefore `OktaOidcStateManager` is stored in keychain using composite key constructed based on configuration. For backward compatibility there is a method `readFromSecureStorage()` that tries to read `OktaOidcStateManager` stored on a legacy way, so user could retrieve previously stored `OktaOidcStateManager` after switching to a newer version of SDK. @@ -384,7 +393,7 @@ stateManager?.introspect(token: accessToken, callback: { payload, error in print("Is token valid? \(isValid)") }) ``` -Sample app [example](https://github.com/okta/samples-ios/blob/master/browser-sign-in/OktaBrowserSignIn/TokensViewController.swift#L38-L47) +Sample app [example](https://github.com/okta/samples-ios/blob/master/browser-sign-in/OktaBrowserSignIn/TokensViewController.swift#L38-L47). #### renew @@ -400,7 +409,7 @@ stateManager?.renew { newAccessToken, error in // renewed TokenManager } ``` -Sample app [example](https://github.com/okta/samples-ios/blob/master/browser-sign-in/OktaBrowserSignIn/TokensViewController.swift#L51-L59) +Sample app [example](https://github.com/okta/samples-ios/blob/master/browser-sign-in/OktaBrowserSignIn/TokensViewController.swift#L51-L59). #### revoke @@ -416,7 +425,7 @@ stateManager?.revoke(accessToken) { response, error in // Token was revoked } ``` -Sample app [example](https://github.com/okta/samples-ios/blob/master/browser-sign-in/OktaBrowserSignIn/TokensViewController.swift#L65-L75) +Sample app [example](https://github.com/okta/samples-ios/blob/master/browser-sign-in/OktaBrowserSignIn/TokensViewController.swift#L65-L75). #### getUser @@ -432,7 +441,7 @@ stateManager?.getUser { response, error in // JSON response } ``` -Sample app [example](https://github.com/okta/samples-ios/blob/master/browser-sign-in/OktaBrowserSignIn/SignInViewController.swift#L28-L38) +Sample app [example](https://github.com/okta/samples-ios/blob/master/browser-sign-in/OktaBrowserSignIn/SignInViewController.swift#L28-L38). #### clear @@ -442,7 +451,7 @@ Removes the local authentication state by removing cached tokens in the keychain ```swift stateManager.clear() ``` -Sample app [example](https://github.com/okta/samples-ios/blob/master/browser-sign-in/OktaBrowserSignIn/SignInViewController.swift#L70) +Sample app [example](https://github.com/okta/samples-ios/blob/master/browser-sign-in/OktaBrowserSignIn/SignInViewController.swift#L70). ## Development @@ -462,7 +471,7 @@ export LOGOUT_REDIRECT_URI={logoutRedirectUri} bash ./scripts/build-and-test.sh ``` -**Note:** *You may need to update the emulator device to match your Xcode version* +**Note:** *You may need to update the emulator device to match your Xcode version.* ## Modify network requests @@ -505,53 +514,9 @@ Known iOS issue where iOS doesn't provide any good ways to terminate active auth You can also consider the following workarounds: - Use `noSSO` option in OIDC configuration object if you don't need SSO capabilites. Also note that this option works only on iOS 13+ versions -- Fork repository and change user-agent implementation(`OIDExternalUserAgentIOS.m`) to use `SFSafariViewController` only. Some pitfalls of this approach described [here](https://github.com/okta/okta-oidc-ios/issues/181) - -### Carthage fails on Xcode 12 -Carthage throws the error when you install the dependencies with the command `carthage update`. The issue happens only on Xcode 12 and higher versions: - -```bash -Build Failed - Task failed with exit code 1: - /usr/bin/xcrun lipo -create /Users/user/Library/Caches/org.carthage.CarthageKit/DerivedData/12.4_12D4e/okta-oidc-ios/3.10.1/Build/Intermediates.noindex/ArchiveIntermediates/okta-oidc/IntermediateBuildFilesPath/UninstalledProducts/iphoneos/OktaOidc.framework/OktaOidc /Users/user/Library/Caches/org.carthage.CarthageKit/DerivedData/12.4_12D4e/okta-oidc-ios/3.10.1/Build/Products/Release-iphonesimulator/OktaOidc.framework/OktaOidc -output /Users/user/{ProjectName}/Carthage/Build/iOS/OktaOidc.framework/OktaOidc - -This usually indicates that project itself failed to compile. Please check the xcodebuild log for more details: /var/folders/2x/q10zv0gx4112thm7dd13szmm0000gn/T/carthage-xcodebuild.YaJjLW.log -``` - -The reason is that Xcode 12 introduced support of the Apple Silicon and Xcode generates duplicated architectures in frameworks. XCFrameworks are still not supported by Carthage, therefore a workaround should be used. - -##### Solution #1: XCFrameworks +- Fork repository and change user-agent implementation(`OIDExternalUserAgentIOS.m`) to use `SFSafariViewController` only. Some pitfalls of this approach described [here](https://github.com/okta/okta-oidc-ios/issues/181). -You should update Carthage to the version 0.37.0 or higher. +## Contributing -1. Run in Terminal the following command: -```bash -brew upgrade carthage -``` -2. Make sure the version is correct: -```bash -carthage version -``` -3. Navigate through Terminal to project folder and run: -```bash -carthage update --use-xcframeworks -``` -4. Open `General` settings tab in Xcode, in the `Frameworks, Libraries, and Embedded Content` section, drag and drop each XCFramework you want to use from the `Carthage/Build` folder. - -> If your existing project is based on discrete framework bundles and you may want to migrate to XCFrameworks, then follow [Carthage migration documentation](https://github.com/Carthage/Carthage#migrating-a-project-from-framework-bundles-to-xcframeworks). - -##### Solution #2: Workaround script - -Launch Carthage via [the script](/scripts/carthage-xcode-12.sh), it will remove duplicated architectures and produce correct framework bundles. - -1. Put the script somewhere to your `PATH` (e.g.: `/usr/local/bin/carthage.sh`). -2. Make the script executable, so open your Terminal and execute: -```sh -chmod +x /{path_to_script_folder}/carthage.sh -``` -3. Run the script whenever you want to use Carthage: -```sh -carthage.sh update -``` +We welcome contributions to all of our open-source packages. Please, see the [contribution guide](CONTRIBUTING.md) to understand how to structure a contribution. -For more information, follow [official Carthage documentation](https://github.com/Carthage/Carthage/blob/master/Documentation/Xcode12Workaround.md#workaround).