Managing Scope Authentication

In this guide users can learn about Scope Authentication methods like Request Secret, Secret Header, and Authorization JWT, how to set them up, and validate them.

Authentication to Runtime

It is important to authenticate Runtime requests to safeguard PlainID Authorization service security and ensure the authenticity of requesting Applications or services seeking sensitive user authorization rights. This section details steps users need to perform to configure Application authentication at the Scope level and implement security measures like the Authorization JWT.

Setting up an Authentication Method in the Scope

Customers are required to set up their integrating Application's Authentication method (Auth Method) at the Scope level, determining how it authenticates to the PDP (Runtime service). Users are still required to send their Client ID in the request body (using the clientId property) or request header (using x-client-id header) for identification purposes. See Managing Scopes to learn more about how to create, manage, and delete Scopes.

Users can choose from the available authentication methods for the relevant Scopes:

A best practice when using the Authorization JWT is to send an Application Service Access Token. An Identity Token can be sent separately as a different JWT used for other purposes like fetching Identity data. In this case, the Authentication for the Runtime through the service or Application can be sent through one JWT in the header, and any Identity information can be sent through an Identity Token JWT.

However, it is still possible to combine the JWTs and use an Identity Token to authenticate to the Runtime.

Error Handling: Using an incorrect secret or an invalid JWT for request authentication results in an error.

To set up Authentication Methods in the Scope:

1. Click on the three dots next to your Environment Name.
2. In the dropdown, click on Settings.
3. In the Environment Settings window, click on the Scopes tile.
4. Click on Create Scope or click on an existing one.
5. Under Auth Method, select the relevant Authentication method.

Managing Secrets

Your Applications can use a Secret key to authenticate the Authorization requests sent to the PDP. To use this authentication method you can manage secret keys for each Scope (ClientID) and send them together with the ClientID in the request body or as a header. Each Scope (ClientID) can have multiple secret keys, which are displayed in a list in the Manage Keys section in the Scope. Existing secret keys are not displayed. To acquire a key, regenerate a key and copy it. Secret Keys can be deleted.

To set up or manage Client Secrets in the Scope:

1. Set Request Secret or Secret Header as the Scope’s Authentication Method.
2. Click Save.
3. On the top right, click on Manage Keys.
4. In the right side-panel set up your Scope Client Keys.
5. Create a new Key or regenerate a new secret.
6. On the bottom, click on Close.

Managing JWT Validation

JWT used for Authentication must be a valid JWT. The validation process consists of validating the JWT signature, expiration and an additional optional validation of a key-value claim. Users can set up multiple validation setting blocks in the event where different JWKs need to be set up.

To set up or manage JWT Validation for the Authentication Methods in the Scope:

1. Set Authorization JWT as the Scope’s Authentication Method.
2. Click Save.
3. On the top-right, click on Manage JWT.
4. Input a JWKs URL. This URL is exposed by your IDP or other JWT Issuer which will be used to fetch keys for the JWT signature validation.
5. Input a Key Refresh Interval (1-24 hours).
6. Input a Validation Claim Key and Value (optional). This field can always be updated. This is used as an extra validation step by checking for a Claim Key in your Authorization JWT and match its value.
7. Click Save.

Note: The Validation Claim Key and Value are verified after the JWKs URL and JWT expiration are validated first. Any value can be used as a claim value if you only want to validate the existence of the claim regardless of its value.