diff --git a/articles/api/authentication/_login.md b/articles/api/authentication/_login.md index d70487e33f..2e1d0fd47e 100644 --- a/articles/api/authentication/_login.md +++ b/articles/api/authentication/_login.md @@ -208,6 +208,7 @@ Make a `GET` call to the `/authorize` endpoint for passive authentication. It re ## Highly Regulated Identity +### Push Authorization Requests (PAR) <%= include('../../_includes/_http-method', { "http_badge": "badge-primary", @@ -231,26 +232,6 @@ Content-Type: 'application/x-www-form-urlencoded' prompt=login|consent|none& organisation=ORGANIZATION ``` -```shell -curl --request POST \ - --url 'https://{yourDomain}/oauth/par' \ - --header 'content-type: application/x-www-form-urlencoded' \ ---data 'response_type=code|code id_token& client_id={yourClientId}& redirect_uri={https://yourApp/callback}&state=STATE&scope=openid|profile|email&code_challenge=CODE_CHALLENGE&code_challenge_method=S256&nonce=NONCE&connection=CONNECTION&prompt=login|consent|none&organisation=ORGANIZATION' -``` - -> RESPONSE SAMPLE: -``` json - -HTTP/1.1 201 Created -Content-Type: application/json - -{ - "request_uri": - "urn:ietf:params:oauth:request_uri:6esc_11ACC5bwc014ltc14eY22c", - "expires_in": 30 -} - -``` ```javascript var request = require("request"); @@ -280,6 +261,29 @@ request(options, function (error, response, body) { }); ``` +```shell +curl --request POST \ + --url 'https://{yourDomain}/oauth/par' \ + --header 'content-type: application/x-www-form-urlencoded' \ +--data 'response_type=code|code id_token& client_id={yourClientId}& redirect_uri={https://yourApp/callback}&state=STATE&scope=openid|profile|email&code_challenge=CODE_CHALLENGE&code_challenge_method=S256&nonce=NONCE&connection=CONNECTION&prompt=login|consent|none&organisation=ORGANIZATION' +``` + +> RESPONSE SAMPLE: +``` json +/** +If the request is successful, `/oauth/par` responds with a `JSON` object containing the `request_uri` property, which can be used at the authorization endpoint, and the `expires_in` value, which indicates the number of seconds the `request_uri` is valid. +*/ + +HTTP/1.1 201 Created +Content-Type: application/json + +{ + "request_uri": + "urn:ietf:params:oauth:request_uri:6esc_11ACC5bwc014ltc14eY22c", + "expires_in": 30 +} +``` + ::: note Highly Regulated Identity is currently available for Enterprise customers under Limited Early Access. To learn more about this program, contact [Auth0 Support](http://support.auth0.com/). ::: @@ -287,7 +291,7 @@ Push Authorization Requests (PAR), a service of [Highly Regulated Identity](http Assuming the call to the `/oauth/par` endpoint is valid, Auth0 will respond with a `redirect_uri` value also used as a parameter for the `/authorize` endpoint. To learn more about configuring PAR, read [Configure Push Authorization Requests (PAR)](https://auth0.com/docs/get-started/applications/configure-par). -### Request Parameters +#### Request Parameters | Parameter | Description | |:-----------------|:------------| | `response_type`
Required | Specifies the token type. We recommend you use code to request an authorization code, or code id_token to receive an authorization code and a [detached signature](https://openid.net/specs/openid-financial-api-part-2-1_0.html#id-token-as-detached-signature). | @@ -302,11 +306,119 @@ Assuming the call to the `/oauth/par` endpoint is valid, Auth0 will respond with | `prompt` | Can be used to force a particular prompt to display, e.g. `prompt=consent` will always display the consent prompt.| | `organization` | ID of the organization to use when authenticating a user. When not provided, if your application is configured to Display Organization Prompt, the user will be able to enter the organization name when authenticating. | -### Remarks +#### Remarks To make a call to the PAR endpoint, you must: - Set the request content type as `application/x-www-form-urlencoded` - Use `strings` for all passed parameters -- Include an additional parameter for application authentication in the request (e.g. `client_secret`, or `client_assertion` and `client_assertion_type` for JSON Web Token Client Authentication, or pass a `client-certificate` and `client-certificate-ca-verified` header when using Mutual TLS). +- Include an additional parameter for application authentication in the request (e.g. `client_secret`, or `client_assertion` and `client_assertion_type` for JSON Web Token Client Authentication, or pass a `client-certificate` and `client-certificate-ca-verified` header when using Mutual TLS). + +### Redirect from PAR to Authorize + +<%= include('../../_includes/_http-method', { + "http_badge": "badge-primary", + "http_method": "GET", + "path": "/authorize", + "link": "#hri" +}) %> + +```http +GET https://{yourDomain}/authorize + request_uri={yourRequestUri}& + client_id={yourClientId} +``` + +After calling the `/oauth/par` endpoint, redirect the end user with a `GET` call to the /authorize endpoint. + +:::note +The `/authorize` endpoint will respond based on the parameters passed to the `/oauth/par` endpoint. If you request a `response_type` of code, you should receive an authorization code to use at the `/oauth/token` endpoint. +::: + +#### Request Parameters +| Parameter | Description | +|:-----------------|:------------| +| `client_id`
Required | The `client_id` of your application. | +| `request_uri`
Required | The `request_uri` value that was received from the `/oauth/par` endpoint. | + +### Exchange an Authorization Code for a Token + +%= include('../../_includes/_http-method', { + "http_badge": "badge-primary", + "http_method": "POST", + "path": "/oauth/token", + "link": "#hri" +}) %> + +```http +POST https://{yourDomain}/oauth/par +Content-Type: 'application/x-www-form-urlencoded' + grant_type=code|code id_token& + client_id={yourClientId}& + code=CODE& + redirect_uri={https://yourApp/callback}& + code_verifier=CODE_VERIFIER +``` + +```javascript +curl --request POST \ + --url 'https://{yourDomain}/oauth/par' \ + --header 'content-type: application/x-www-form-urlencoded' \ +--data 'grant_type=authorization_code& client_id={yourClientId}& code=CODE&redirect_uri={https://yourApp/callback}&code_verifier=CODE_VERIFIER' +``` + +> RESPONSE SAMPLE: +``` json +/** +The `/oauth/token` endpoint will respond with a JSON object containing an `id_token` property, and potentially also a `refresh_token` if one was requested. +*/ +HTTP/1.1 200 OK +Content-Type: application/json +{ + "refresh_token":"GEbRxBN...edjnXbL", + "id_token":"eyJ0XAi...4faeEoQ", + "token_type":"Bearer", + "expires_in":86400 +} +``` + +```shell +var request = require("request"); + +var options = { method: 'POST', + url: 'https://{yourDomain}/oauth/token, + headers: { 'content-type': 'application/x-www-form-urlencoded' }, + form: { + grant_type: 'authorization_code', + client_id: '{yourClientId}', + code: 'CODE', + redirect_uri: '{https://yourApp/callback}', + code_verifier: 'CODE_VERIFIER' + } +}; + +request(options, function (error, response, body) { + if (error) throw new Error(error); + + console.log(body); +}); +``` + +When users are redirected to `/authorize`, you need to make a `POST` call to the `oauth/token` endpoint to exchange an authorization code for an access and/or an ID token. + +#### Request Parameters +| Parameter | Description | +|:-----------------|:------------| +| `grant_type`
Required | Denotes the flow. Assuming you have an authorization code from the /authorize endpoint, use `authorization_code`. | +| `code` | The authorization code from the initial `/authorize` call. | +| `client_id`
Required | The `client_id` of your application. | +| `request_uri`
Required | This is required only if it was set at the `GET` `/oauth/par` endpoint. The values must match. | +| `code_verifier`
Recommended | Cryptographically random key used to generate the `code_challenge` passed to `/oauth/par`. If the `code_challenge` parameter is passed in the call to `/oauth/par`, this is required. | + +#### Remarks + +To make a call to `/oauth/token` endpoint, you must: +- Set the request content type as `application/x-www-form-urlencoded` +- Use `strings` for all passed parameters +- Include an additional parameter for application authentication in the request (e.g. `client_secret`, or `client_assertion` and `client_assertion_type` for JSON Web Token Client Authentication, or pass a `client-certificate` and `client-certificate-ca-verified` header when using Mutual TLS). ## Test with Authentication API Debugger