Skip to content

Commit

Permalink
Update Readme (#306)
Browse files Browse the repository at this point in the history 
* Update Readme

* Add a note about Swift Authn SDK
  • Loading branch information
@oleggnidets-okta
oleggnidets-okta authored Aug 5, 2021
1 parent 949a8ca commit 637b6c4
Showing 1 changed file with 34 additions and 69 deletions.
103 changes: 34 additions & 69 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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**

Expand All @@ -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)

<!-- /TOC -->

Expand All @@ -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

Expand Down Expand Up @@ -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).
Expand Down Expand Up @@ -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: [
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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

Expand All @@ -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 {
Expand All @@ -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.

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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).

0 comments on commit 637b6c4

Please sign in to comment.