Skip to content

Commit 120c9d3

Browse files
rkhorianderrkhoriander
authored
Merge pull request #8191 from auth0/docs-875-native-siwa
Sign In With Apple Setup and Configuration
2 parents 14f2f02 + 686c287 commit 120c9d3

17 files changed

+429
-160
lines changed

‎articles/api/authentication/api-authz/_get-token.md

+103-7
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,17 @@
11
# Get Token
22

33
Use this endpoint to:
4-
- Get an <dfn data-key="access-token">Access Token</dfn> in order to call an API. You can, optionally, retrieve an ID Token and a <dfn data-key="refresh-token">Refresh Token</dfn> as well.
5-
- Refresh your Access Token, using a Refresh Token you got during authorization.
4+
- Get an <dfn data-key="access-token">Access Token</dfn> in order to call an API. Optionally, you can also retrieve an ID Token and a <dfn data-key="refresh-token">Refresh Token</dfn>.
5+
- Refresh your Access Token using a Refresh Token you got during authorization.
66

77
Note that the only OAuth 2.0 flows that can retrieve a Refresh Token are:
88
- [Authorization Code Flow (Authorization Code)](/flows/concepts/auth-code)
99
- [Authorization Code Flow with PKCE (Authorization Code with PKCE)](/flows/concepts/auth-code-pkce)
1010
- [Resource Owner Password](/api-auth/grant/password)
1111
- [Device Authorization Flow](/flows/concepts/device-auth)
12+
- Token Exchange\*
13+
14+
\* Only for certain native social profiles
1215

1316
## Authorization Code Flow
1417

@@ -75,7 +78,7 @@ This is the flow that regular web apps use to access an API. Use this endpoint t
7578

7679
| Parameter | Description |
7780
|:-----------------|:------------|
78-
| `grant_type` <br/><span class="label label-danger">Required</span> | Denotes the flow you are using. For Authorization Code use `authorization_code`. |
81+
| `grant_type` <br/><span class="label label-danger">Required</span> | Denotes the flow you are using. For Authorization Code, use `authorization_code`. |
7982
| `client_id` <br/><span class="label label-danger">Required</span> | Your application's Client ID. |
8083
| `client_secret` <br/><span class="label label-danger">Required</span> | Your application's Client Secret. |
8184
| `code` <br/><span class="label label-danger">Required</span> | The Authorization Code received from the initial `/authorize` call. |
@@ -91,13 +94,13 @@ This is the flow that regular web apps use to access an API. Use this endpoint t
9194

9295
<%= include('../../../_includes/_test-this-endpoint') %>
9396

94-
If you have just executed the [Authorization Code Grant](#authorization-code-grant) you should already have a code set at the **Authorization Code** field of the *OAuth2 / OIDC* tab. If so, click **OAuth2 Code Exchange**, otherwise follow the instructions.
97+
If you have just executed the [Authorization Code Grant](#authorization-code-grant), you should already have a code set at the **Authorization Code** field of the *OAuth2 / OIDC* tab. If so, click **OAuth2 Code Exchange**; otherwise, follow the instructions.
9598

9699
1. At the *Configuration* tab, set the **Application** field to the application you want to use for the test.
97100

98101
1. Copy the <dfn data-key="callback">**Callback URL**</dfn> and set it as part of the **Allowed Callback URLs** of your [Application Settings](${manage_url}/#/applications).
99102

100-
1. At the *OAuth2 / OIDC* tab, set the field **Authorization Code** to the code you retrieved from [Authorization Code Grant](#authorization-code-grant). Click **OAuth2 Code Exchange**.
103+
1. At the *OAuth2 / OIDC* tab, set the field **Authorization Code** to the code you retrieved from the [Authorization Code Grant](#authorization-code-grant). Click **OAuth2 Code Exchange**.
101104

102105

103106
### More Information
@@ -166,7 +169,6 @@ Content-Type: application/json
166169
This is the flow that mobile apps use to access an API. Use this endpoint to exchange an Authorization Code for a Token.
167170

168171

169-
170172
### Request Parameters
171173

172174
| Parameter | Description |
@@ -577,7 +579,101 @@ Use this endpoint to refresh an <dfn data-key="access-token">Access Token</dfn>
577579

578580
1. At the *OAuth2 / OIDC* tab, set the field **Refresh Token** to the Refresh Token you have. Click **OAuth2 Refresh Token Exchange**.
579581

580-
581582
### More Information
582583

583584
- [Refresh Token](/tokens/refresh-token)
585+
586+
## Token Exchange for Native Social
587+
588+
```http
589+
POST https://${account.namespace}/oauth/token
590+
Content-Type: application/x-www-form-urlencoded
591+
592+
grant_type=urn:ietf:params:oauth:grant-type:token-exchange&subject_token=SUBJECT_TOKEN&subject_token_type=SUBJECT_TOKEN_TYPE&client_id=${account.clientId}&audience=API_IDENTIFIER&scope=SCOPE
593+
```
594+
595+
```shell
596+
curl --request POST \
597+
--url 'https://${account.namespace}/oauth/token' \
598+
--header 'content-type: application/x-www-form-urlencoded' \
599+
--data 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange&subject_token=SUBJECT_TOKEN&subject_token_type=SUBJECT_TOKEN_TYPE&client_id=${account.clientId}&audience=API_IDENTIFIER&scope=SCOPE'
600+
}'
601+
```
602+
603+
```javascript
604+
var request = require("request");
605+
606+
var options = { method: 'POST',
607+
url: 'https://${account.namespace}/oauth/token',
608+
headers: { 'content-type': 'application/x-www-form-urlencoded' },
609+
form:
610+
{ grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
611+
subject_token: 'SUBJECT_TOKEN',
612+
subject_token_type: 'SUBJECT_TOKEN_TYPE',
613+
client_id: '${account.clientId}',
614+
audience: 'API_IDENTIFIER',
615+
scope: 'SCOPE',
616+
};
617+
618+
request(options, function (error, response, body) {
619+
if (error) throw new Error(error);
620+
621+
console.log(body);
622+
});
623+
```
624+
625+
> RESPONSE SAMPLE:
626+
627+
```JSON
628+
HTTP/1.1 200 OK
629+
Content-Type: application/json
630+
{
631+
"access_token": "eyJz93a...k4laUWw",
632+
"id_token": "eyJ...0NE",
633+
"refresh_token": "eyJ...MoQ",
634+
"expires_in":86400,
635+
"token_type":"Bearer"
636+
}
637+
```
638+
639+
<%= include('../../../_includes/_http-method', {
640+
"http_badge": "badge-success",
641+
"http_method": "POST",
642+
"path": "/oauth/token",
643+
"link": "#token-exchange-native-social"
644+
}) %>
645+
646+
:::warning
647+
This flow is intended for use with native social interactions **only**. Use of this flow outside of a native social setting is highly discouraged.
648+
:::
649+
650+
When a non-browser-based solution (such as a mobile platform's SDK) authenticates the user, the authentication will commonly result in artifacts being returned to application code. In such situations, this grant type allows for the Auth0 platform to accept artifacts from trusted sources and issue tokens in response. In this way, apps making use of non-browser-based authentication mechanisms (as are common in native apps) can still retrieve Auth0 tokens without asking for further user interaction.
651+
652+
Artifacts returned by this flow (and the contents thereof) will be determined by the `subject_token_type` and configuration settings of the tenant.
653+
654+
### Request Parameters
655+
656+
| Parameter | Description |
657+
|:-----------------|:------------|
658+
| `grant_type` <br/><span class="label label-danger">Required</span> | Denotes the flow you are using. For Token Exchange for Native Social, use `urn:ietf:params:oauth:grant-type:token-exchange`. |
659+
| `subject_token` <br/><span class="label label-danger">Required</span> | Externally-issued identity artifact, representing the user. |
660+
| `subject_token_type` <br/><span class="label label-danger">Required</span> | Identifier that indicates the type of `subject_token`. Currently supported native social values are: `http://auth0.com/oauth/token-type/apple-authz-code`. |
661+
| `client_id` <br/><span class="label label-danger">Required</span> | Your application's Client ID. |
662+
| `audience` | The unique identifier of the target API you want to access. |
663+
| `scope` | String value of the different <dfn data-key="scope">scopes</dfn> the application is requesting. Multiple scopes are separated with whitespace. |
664+
665+
### Request headers
666+
667+
| Parameter | Description |
668+
|:-----------------|:------------|
669+
| `auth0-forwarded-for` | End-user IP as a string value. Set this if you want brute-force protection to work in server-side scenarios. For more information on how and when to use this header, refer to [Using resource owner password from server-side](/api-auth/tutorials/using-resource-owner-password-from-server-side). |
670+
671+
### Remarks
672+
673+
- The <dfn data-key="scope">scopes</dfn> issued to the application may differ from the scopes requested. In this case, a `scope` parameter will be included in the response JSON.
674+
- If you don't request specific scopes, all scopes defined for the audience will be returned due to the implied trust to the application in this grant. You can customize the scopes returned in a rule. For more information, refer to [Calling APIs from Highly Trusted Applications](/api-auth/grant/password).
675+
676+
### More Information
677+
- [Add Sign In with Apple to Native iOS Apps](/connections/apple-siwa/add-siwa-to-native-app)
678+
- [iOS Swift - Sign In with Apple Quickstart](/quickstart/native/ios-swift-siwa)
679+

‎articles/connections/apple-setup.md

-114
This file was deleted.

‎articles/connections/apple-siwa/add-siwa-to-native-app.md

+93
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
title: Add Sign In with Apple to Native iOS Apps
3+
description: Learn how to add native login functionality to your native app with Apple.
4+
topics:
5+
- authentication
6+
- connections
7+
- social
8+
- apple
9+
contentType: how-to
10+
useCase:
11+
- add-login
12+
- customize-connections
13+
- add-idp
14+
---
15+
# Add Sign In with Apple to Native iOS Apps
16+
17+
You can add functionality to your native iOS application to allow your users to authenticate using Sign In with Apple. For more implementation details, you can try the Auth0 [iOS Swift - Sign In with Apple Quickstart](/quickstart/native/ios-swift-siwa).
18+
19+
## How it works
20+
21+
For a native app, the Sign in with Apple login flow works as follows:
22+
23+
![Sign In with Apple Authentication Flow](/media/articles/connections/social/apple/apple-siwa-authn-flow.png)
24+
25+
* **Steps 1 & 2**: User authenticates via Apple's SDK on their iOS device, and receive an authorization code in the response. The user does not have to leave the app and use a browser to log in.
26+
* **Step 3**: The application calls Auth0's `/oauth/token` endpoint to exchange the Apple authorization code for Auth0 tokens.
27+
* **Step 4 & 5**: The Auth0 platform exchanges the Authorization code with Apple for tokens. Auth0 validates the tokens, and uses the claims in the tokens to construct the identity of the user.
28+
* **Step 6**: Auth0 saves the user profile, executes rules and authorization, then issues Auth0 access tokens (refresh tokens and ID tokens) as requested. These tokens are used to protect your APIs and users managed by Auth0.
29+
30+
## Prerequisites
31+
32+
Before you configure Sign In with Apple for your native app in Auth0, you must:
33+
34+
* Have an [Apple Developer](https://developer.apple.com/programs/) account, which is a paid account with Apple. (There is no free trial available unless you are part of their [iOS Developer University Program](https://developer.apple.com/support/compare-memberships/).)
35+
36+
* Have set up a [custom domain](/custom-domains) on your Auth0 tenant (because you must be able to do domain verification with Apple).
37+
38+
* [Register Apps in the Apple Developer Portal](/connections/apple-siwa/set-up-apple). Make a note of the following IDs and key for the application connection settings in the Auth0 Dashboard:
39+
40+
* App ID
41+
* Apple Team ID
42+
* Client Secret Signing Key
43+
* Client Signing Key ID (optional)
44+
45+
::: note
46+
If you are using the Classic Universal Login flow or embedding `Lock.js` in your application, make sure you are using `Lock.js` version 11.16 or later.
47+
:::
48+
49+
## Configure and enable the connection in Auth0
50+
51+
Once you have the credentials you need from your Apple Developer account, you need to configure the application client and the connection settings in Auth0.
52+
53+
1. On the Dashboard, go to [Applications](${manage_url}/#/applications), choose your application, and click the gear icon to view the settings page.
54+
55+
2. At the bottom of the page, click **Show Advanced Settings** and go to the **Device Settings** tab. Under **Native Social Login**, enable the **Enable Sign In with Apple** toggle.
56+
57+
![Application Client Settings: Advanced Device Settings](/media/articles/connections/social/apple/apple-app-mobile-settings.png)
58+
59+
3. Under **iOS**, fill in the **App ID** field with the native app's App ID/Bundle Identifier.
60+
61+
4. Go to [Connections > Social](${manage_url}/#/connections/social) and click on the **Apple** connection.
62+
63+
5. On the **Settings** tab, fill in the following fields:
64+
65+
* **Apple Team ID**
66+
* **Client Secret Signing Key**
67+
* **Key ID** (Apple will accept the key without the ID)(optional)
68+
69+
![Application Connection Settings](/media/articles/connections/social/apple/apple-connection.png)
70+
71+
6. Click **Save**.
72+
73+
::: note
74+
Native apps cannot be tested from the browser. This means that the **TRY** button on the Apple connection is used exclusively for testing web-based flows.
75+
:::
76+
77+
## Logout
78+
Since the Native iOS login implementation does not make use of standard browser-based flows, application owners must also take care to perform logout appropriately. When an application needs to perform a logout, it must take the following actions:
79+
80+
* [Revoke the Auth0 Refresh Token](/api/authentication#revoke-refresh-token)
81+
* Delete the Auth0 refresh token stored in the iCloud Keychain
82+
* Delete the Apple user identifier stored in the iCloud keychain
83+
84+
Also, keep in mind that logout can result from user actions (i.e., clicking a "log out" button) or from a user revoking access to the given app. The latter will be indicated through the native [ASAuthorizationAppleIDProvider.getCredentialState](https://developer.apple.com/documentation/authenticationservices/asauthorizationappleidprovider/3175423-getcredentialstate) method.
85+
86+
:::note
87+
One nuance of Apple's IdP is that it only returns requested scopes (such as email, first name, and last name) in the ID token on the **first** response. More destructive approaches to logout (such as deleting the user) could result in loss of profile information, which would require end users to unauthorize and reauthorize an app.
88+
:::
89+
90+
## Keep reading
91+
92+
* [Rate Limits on Native Social Logins](/policies/rate-limits#limits-on-native-social-logins)
93+
* [Test Sign In with Apple Configuration](/connections/apple-siwa/test-siwa-connection)

0 commit comments

Comments
 (0)