Managing Scope Authentication
    • 21 Feb 2024
    • 4 Minutes to read
    • Dark
      Light
    • PDF

    Managing Scope Authentication

    • Dark
      Light
    • PDF

    Article summary

    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:

    Authentication MethodDescription
    Request SecretRequest Secrets can be generated to each Scope and then sent as a means of Authentication in the request body.
    Secret HeaderHeaders in an HTTP request are used to convey additional information about the request. This can include Authentication details. In this case, a Scope secret can be included in the request headers to authenticate the client making the request.
    Authorization JWTIf an Application wants to authenticate using a Token instead of a secret, it can send an Authorization JWT as a means of authentication. Ensure that your Authorization JWT is valid for a successful authentication process if you are using it instead of a Secret as an Authentication method.

    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.

    Note

    Existing Scopes will not have any Authentication Method defined by default. Their behavior is not expected to change.

    We advise our customers to define an Authentication Method to each of their Scopes and adjust them to their preferred Authentication flow.

    The option to have a Scope with an undefined Authentication Method is temporary and will be deprecated soon.

    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.

    Important

    Up until the PlainID 5.2402 Release, JWKs URLs for JWT validations were defined in the PAA side-panel Settings.

    We advise our customers to copy their JWKs URLs to the relevant Scopes and remove them from the PAA settings, as this option to set up JWKs URLs in the PAA settings would be temporary and is set to be deprecated.

    If you have any questions, contact our Global Services Team for more information.


    Was this article helpful?