diff --git a/README.md b/README.md index 8f5ae0c5..1db15f32 100644 --- a/README.md +++ b/README.md @@ -10,20 +10,33 @@ Swift toolkit that lets you communicate efficiently with many of the [Auth0 API](https://auth0.com/docs/api/info) functions and enables you to seamlessly integrate the Auth0 login. +## Important Notice +[Behaviour changes in iOS 13](https://github.com/auth0/Auth0.swift/pull/297) related to Web Authentication require that developers using Xcode 11 with this library **must** compile using Swift 5.x. This *should* be the default setting applied when updating, unless it has been manually set. However, we recommend checking that this value is set correctly. + +## Table of Contents + +- [Requirements](#requirements) +- [Installation](#installation) +- [Getting Started](#getting-started) +- [Next Steps](#next-steps) +- [What is Auth0?](#what-is-auth0) +- [Create a Free Auth0 Account](#create-a-free-auth0-account) +- [Issue Reporting](#issue-reporting) +- [Author](#author) +- [License](#license) + ## Requirements - iOS 9+ / macOS 10.11+ / tvOS 9.0+ / watchOS 2.0+ - Xcode 10.x/11.x - Swift 4.x/5.x -## Important Notice -Behaviour changes in iOS 13 related to Web Authentication require that developers using Xcode 11 with this library **must** compile using Swift 5.x. This *should* be the default setting applied when updating, unless it has been manually set. However, we recommend checking that this value is set correctly. ## Installation #### Carthage -If you are using Carthage, add the following lines to your `Cartfile`: +If you are using [Carthage](https://github.com/Carthage/Carthage), add the following lines to your `Cartfile`: ```ruby github "auth0/Auth0.swift" ~> 1.20 @@ -49,16 +62,16 @@ Then run `pod install`. > ### Upgrade Notes > If you are using the [clearSession](https://github.com/auth0/Auth0.swift/blob/master/Auth0/WebAuth.swift#L248) method in iOS 11+, you will need to ensure that the **Callback URL** has been added to the **Allowed Logout URLs** section of your application in the [Auth0 Dashboard](https://manage.auth0.com/#/applications/). -## Getting started +## Getting Started -### Authentication with hosted login page (iOS Only) +### Authentication with Universal Login (iOS Only) 1. Import **Auth0** into your project. ```swift import Auth0 ``` -2. Present the hosted login page. +2. Present the Universal Login page. ```swift Auth0 .webAuth() @@ -73,7 +86,7 @@ Auth0 } ``` -> This snippet sets the `audience` to ensure OIDC compliant responses, this can also be achieved by enabling the **OIDC Conformant** switch in your Auth0 dashboard under `Application / Settings / Advanced OAuth`. For more information please check [this documentation](https://auth0.com/docs/api-auth/intro#how-to-use-the-new-flows). +> This snippet sets the `audience` to ensure OIDC compliant responses, this can also be achieved by enabling the **OIDC Conformant** switch in your Auth0 dashboard under `Application / Settings / Advanced / OAuth`. For more information please check the [OIDC Conformant Authentication Adoption Guide](https://auth0.com/docs/api-auth/tutorials/adoption). 3. Allow Auth0 to handle authentication callbacks. In your `AppDelegate.swift` add the following: ```swift @@ -86,7 +99,7 @@ func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpe In order to use Auth0 you need to provide your Auth0 **ClientId** and **Domain**. -> Auth0 ClientId & Domain can be found in your [Auth0 Dashboard](https://manage.auth0.com/#/applications/) +> Auth0 ClientId & Domain can be found in your [Auth0 Dashboard](https://manage.auth0.com/#/applications/). #### Adding Auth0 Credentials @@ -131,7 +144,7 @@ In your application's `Info.plist` file, register your iOS Bundle Identifer as a > If your `Info.plist` is not shown in this format, you can **Right Click** on `Info.plist` in Xcode and then select **Open As / Source Code**. -Finally, go to your [Auth0 Dashboard](https://manage.auth0.com) and make sure that your application's **Allowed Callback URLs** field contains the following entry: +Finally, go to your [Auth0 Dashboard](https://manage.auth0.com/#/applications/) and make sure that your application's **Allowed Callback URLs** field contains the following entry: ```text YOUR_BUNDLE_IDENTIFIER://YOUR_AUTH0_DOMAIN/ios/YOUR_BUNDLE_IDENTIFIER/callback @@ -169,7 +182,7 @@ Auth0 #### Renew user credentials -Use a [Refresh Token](https://auth0.com/docs/tokens/refresh-token/) to renew user credentials. It's recommended that you read and understand the refresh token process before implementing. +Use a [Refresh Token](https://auth0.com/docs/tokens/concepts/refresh-tokens) to renew user credentials. It's recommended that you read and understand the refresh token process before implementing. ```swift Auth0 @@ -244,7 +257,7 @@ credentialsManager.enableBiometrics(withTitle: "Touch to Login") ### Sign in With Apple -If you've added [the Sign In with Apple Flow to Your App](https://developer.apple.com/documentation/authenticationservices/adding_the_sign_in_with_apple_flow_to_your_app) you can use the string value from the `authorizationCode` property obtained after a successful Apple authentication to perform a token exchange for Auth0 tokens. +If you've added [the Sign In with Apple Flow to Your App](https://developer.apple.com/documentation/authenticationservices/implementing_user_authentication_with_sign_in_with_apple) you can use the string value from the `authorizationCode` property obtained after a successful Apple authentication to perform a token exchange for Auth0 tokens. ```swift Auth0 @@ -260,12 +273,12 @@ Auth0 } ``` -Find out more about [Setting up Sign in with Apple](https://auth0.com/docs/connections/apple-setup) with Auth0. +Find out more about [Setting up Sign in with Apple](https://auth0.com/docs/connections/apple-siwa/set-up-apple) with Auth0. ### Authentication API (iOS / macOS / tvOS) The Authentication API exposes AuthN/AuthZ functionality of Auth0, as well as the supported identity protocols like OpenID Connect, OAuth 2.0, and SAML. -We recommend using our Hosted Login Page but if you wish to build your own UI you can use our API endpoints to do so. However some Auth flows (Grant types) are disabled by default so you will need to enable them via your Auth0 Dashboard as explained in [this guide](https://auth0.com/docs/clients/client-grant-types#edit-available-grant_types). +We recommend using [Universal Login](https://auth0.com/docs/universal-login) but if you wish to build your own UI, you can use our API endpoints to do so. However, some Auth flows (grant types) are disabled by default so you must enable them via your Auth0 Dashboard as explained in [Application Grant Types](https://auth0.com/docs/applications/concepts/application-grant-types#edit-available-grant_types). These are the required Grant Types that needs to be enabled in your application: @@ -291,7 +304,7 @@ Auth0 } ``` -> This requires `Password` Grant or `http://auth0.com/oauth/grant-type/password-realm` +> This requires `Password` Grant or `http://auth0.com/oauth/grant-type/password-realm`. #### Sign Up with database connection @@ -318,7 +331,7 @@ Auth0 ### Custom Domains If you are using the [Custom Domains](https://auth0.com/docs/custom-domains) feature and need to use an Auth0 endpoint -such as `/userinfo`, please use the Auth0 domain specified for your Application in the [Auth0 Dashboard](https://auth0.com/docs/dashboard). +such as `/userinfo`, please use the Auth0 domain specified for your Application in the [Auth0 Dashboard](https://manage.auth0.com/#/applications/). Example: `.audience("https://{YOUR_AUTH0_DOMAIN}/userinfo")` @@ -326,7 +339,7 @@ Example: `.audience("https://{YOUR_AUTH0_DOMAIN}/userinfo")` You can request more information about a user's profile and manage the user's metadata by accessing the Auth0 [Management API](https://auth0.com/docs/api/management/v2). For security reasons native mobile applications are restricted to a subset of User based functionality. -You can find a detailed guide in this [iOS Swift QuickStart](https://auth0.com/docs/quickstart/native/ios-swift/03-user-sessions#managing-metadata) +You can find a detailed guide in this [iOS Swift QuickStart](https://auth0.com/docs/quickstart/native/ios-swift/03-user-sessions#managing-metadata). #### Link an account @@ -381,25 +394,25 @@ Connection: keep-alive Auth0 helps you to: -* Add authentication with [multiple authentication sources](https://docs.auth0.com/identityproviders), either social like **Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Box, Salesforce, amont others**, or enterprise identity systems like **Windows Azure AD, Google Apps, Active Directory, ADFS or any SAML Identity Provider**. -* Add authentication through more traditional **[username/password databases](https://docs.auth0.com/mysql-connection-tutorial)**. -* Add support for **[linking different user accounts](https://docs.auth0.com/link-accounts)** with the same user. -* Support for generating signed [JSON Web Tokens](https://docs.auth0.com/jwt) to call your APIs and **flow the user identity** securely. +* Add authentication with [multiple authentication sources](https://auth0.com/docs/identityproviders), either social like **Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Box, Salesforce, amont others**, or enterprise identity systems like **Windows Azure AD, Google Apps, Active Directory, ADFS or any SAML Identity Provider**. +* Add authentication through more traditional **[username/password databases](https://auth0.com/docs/connections/database/custom-db)**. +* Add support for **[linking different user accounts](https://auth0.com/docs/link-accounts)** with the same user. +* Support for generating signed [JSON Web Tokens](https://auth0.com/docs/tokens/concepts/jwts) to call your APIs and **flow the user identity** securely. * Analytics of how, when and where users are logging in. -* Pull data from other sources and add it to the user profile, through [JavaScript rules](https://docs.auth0.com/rules). +* Pull data from other sources and add it to the user profile, through [JavaScript rules](https://auth0.com/docs/rules). -## Create a free Auth0 Account +## Create a Free Auth0 Account 1. Go to [Auth0](https://auth0.com) and click Sign Up. 2. Use Google, GitHub or Microsoft Account to login. ## Issue Reporting -If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/whitehat) details the procedure for disclosing security issues. +If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/responsible-disclosure-policy/) details the procedure for disclosing security issues. ## Author -[Auth0](auth0.com) +[Auth0](https://auth0.com) ## License