search
how tos

Get a Token Using PKCE

Apps such as Native/SPA apps store their code on user devices and browsers. That can be a risk when you include the client secret in that code. With the Proof Key for Code Exchange (PKCE) (pronounced pixie), ForgeRock Identity Cloud Express lets you acquire access tokens without that app client secret.

Native apps and SPAs store their code on user devices and browsers. If you were to you include the client secret in that code, you would create a security risk. This isn’t an issue for service apps because users typically don’t sign in to service apps.

Using the Proof Key for Code Exchange (PKCE) (pronounced pixie), Express lets you get access tokens that don’t contain the app client secret.

Although the code for web apps is stored on servers, PKCE can also reduce risks for web apps.

Before You Begin

  1. Add a user to the tenant.
  2. Add an app to the tenant.
    • For this example, set a redirect URI of https://example.com/homeLogin/.
    • See Manage Apps.

After you’ve set up a user and an app in the tenant, you can:

For a working example of the following REST calls, see the Express Postman Colletion.

Using PKCE for Native/SPA Apps

Run the following REST calls for Native/SPA apps:

1) Get an SSO token. With the username and password of a regular user, you can get an SSO token with the following REST call:

content_copy COPY

curl -X POST \
  https://openam-{tenantName}.forgeblocks.com/am/json/realms/root/authenticate \
  -H 'Accept-API-Version: resource=2.0,protocol=1.0' \
  -H 'X-OpenAM-Username: {username}' \
  -H 'X-OpenAM-Password: {password}' \

2) Substitute appropriate values for {tenantName}, {username}, and {password}.

The output includes the tokenId, the SSO token for the given user. The Express Postman Collection includes a script that copies the SSO token to the ssoToken property:

alt text

3) Get an authorization code. Once you have a verified authorization code, you can exchange it for an access token.

4) To set up the following REST calls, find your values for the following properties:

Property Description
tenantName Name of the tenant. This is included in the URL for the console.
client_id ID of the app
redirect_uri The URI to redirect users to sign in to your app
code_challenge A string based on the code_verifier
code_challenge_method Defines whether the code_challenge is encoded; S256 assigns base64 encoding
state A base64-encoded string
code_verifier A cryptographically random string

5) Substitute those properties in the following URL, then go to that URL in your browser:

content_copy COPY

https://openam-{tenantName}.forgeblocks.com/am/oauth2/realms/root/authorize?grant_type=authorization_code&client_id=<client_id_of_your_native_spa_app>&response_type=code&scope=openid&redirect_uri=https://example.com/homeLogin/&code_challenge=<generated_from_a_code_verifier>&code_challenge_method=S256&state=<arbitrary_string>'

You should be redirected to a screen where you can find the authorization code in the URL, which you can use in the next step:

alt text

6) Use the authorization code and the code verifier to get your access token, ID token, and (with an appropriately configured app) a refresh token:

content_copy COPY

curl -X POST \
  https://openam-{tenantName}.forgeblocks.com/am/oauth2/realms/root/access_token \
  -d 'grant_type=authorization_code' \
  -d 'code=<authorization_code>' \
  -d 'client_id=<native_spa_app_client_id>' \
  -d 'redirect_uri=https://example.com/homeLogin/'
  -d 'code_verifier=<code_verifier>'

If successful, you’ll have appropriate tokens. And you won’t have to risk storing the app client secret on a user browser or device.

Using PKCE for Web Apps

The process of acquiring access, ID, and refresh tokens using PKCE for web apps is similar to that for Native/SPA apps. The big difference is that because the app isn’t stored on user devices, it’s less risky to include a client secret:

1) Get the SSO token for a user. You can use the same command described in the PKCE and Native/SPA Apps section.

2) Substitute values in the following URL, based on the table shown in the PKCE and Native/SPA Apps:

content_copy COPY

https://openam-{tenantName}.forgeblocks.com/am/oauth2/realms/root/authorize?grant_type=authorization_code&client_id=<client_id_of_your_native_web_app>&response_type=code&scope=openid&redirect_uri=https://example.com/homeLogin/&code_challenge=<generated_from_a_code_verifier>&code_challenge_method=S256&state=<arbitrary_string>'

You should be redirected to a screen where you can sign in to an existing account:

alt text

3) When you sign in, you should see a “code” in the URL, which you can use in the next step:

alt text

4) Use the authorization code and the code verifier to get your access token, ID token, and (with an appropriately configured app) a refresh token:

content_copy COPY

curl -X POST \
  https://openam-{tenantName}.forgeblocks.com/am/oauth2/realms/root/access_token \
  -d 'grant_type=authorization_code' \
  -d 'code={authorization_code}' \
  -d 'client_id={native_web_app_client_id}' \
  -d 'redirect_uri=https://example.com/homeLogin/' \
  -d 'code_verifier={code_verifier}'

In the output, you should now have appropriate tokens.

For questions or feedback, contact us.