Scope Consent

Overview

Scope consent is a token condition evaluated before token issuance. When user consent is required for specific scopes, the authentication flow pauses to obtain explicit user authorization.

Introduction to Scope Consent

What are scopes?

Scopes are a concept used in the OAuth 2.0 specification to specify access privileges when issuing an access Token.

OpenId Connect (OIDC) is built upon OAuth 2.0 and has a notion of scopes, which in this case specifies the information returned about the authenticated user.

In that context, they are meant to secure the user's data, for example, the scope email to secure the email attributes or the profile to secure the profile user data like given_name and family_name. Hence, they may depend on specific registration fields. Defining the scope also limits app data access to different user levels.

When is a user asked for scope consent?

Having this in mind, when requesting a profile, email, or any other scope, the users' data can be accessed. As soon as a user's data can be accessed through an application, consent might be required.

Criteria	Example	Configuration
The consent will be requested client-based and only once per client	So when the user agrees, e.g., for your webshop to accept the scope consent, they will be asked again when using your mobile application.	View API
scope-level requirement	This is a scope setting that can be enabled in the scope management section. Thereby, all users will be prompted to accept this scope consent when authenticating for a particular client.
Third Party Application	A Third Party Client is an untrusted client. The user data will then be issued either as id_token or using the userinfo-endpoint of the application. These third-party clients require a transfer of personal data, but before allowing the transfer of personal data, the user's consent needs to be requested. A third-party client type will always request consent for the scopes that were requested. (excluded: cidaas-prefix scopes, openid, offline_access )
prompt=consent	The consent will be requested request-based	Even if the user already agreed to this scope for a particular client, the prompt=consent allows them to present the scope consent again if scope-level is required or for a third-party client.

Benefits

• Users explicitly authorize what information is shared
• Granular control over data access (email, profile, etc.)
• Transparency about what applications can access
• Ability to deny unnecessary data requests
• Applications granted only necessary permissions
• Reduces attack surface for malicious actors
• Limits scope of potential data breaches

How it works

When scope consent is required:

1. Token generation pauses - The issuance process is interrupted
2. User is informed - The requested scopes requiring consent are displayed
3. Consent is required - The user must explicitly approve the scopes before receiving a token

This ensures users maintain control over what permissions they grant to applications.

Understanding the Flow and APIs

Step 1: Redirection to consent_scopes

After login the user will be redirected to accept the scope consent. This might look like this:

curl 'https://demo.cidaas.de/identity/consent_scopes?track_id=958ccb4c-3985-4b17-b325-14cd10da292e&requestId=d8ada94d-47e6-4133-9ae3-b5f0a864f7f5&sub=a05b5498-a8f2-4cf4-89b9-bd2fc0b5e13b&q=a05b5498-a8f2-4cf4-89b9-bd2fc0b5e13b&client_id=69d81af1-e4f6-4062-8754-9ee5752a7ca4' \
  --compressed

The URL is defined by the hosted page key: consent_scopes.

It returns a track_id which is required as input for the Step 2. Furthermore, the hosted page consent_scopes is used, which can be configured using the admin dashboard or administrative APIs for managing hosted pages. Furthermore, the track_id is required as input for Step 4 to continue the login process.

Step 2: Understanding the Response of Token Prelogin Metadata

The API to return the prelogin metadata information allows you to actually find out which scopes require user consent.

curl 'https://demo.cidaas.de/token-srv/prelogin/metadata/958ccb4c-3985-4b17-b325-14cd10da292e?acceptLanguage=en-US' \
  --compressed

Retrieving the token prevalidation information will reveal which scopes are in status OPEN, so the user must consent to those scopes to be able to continue. This response body illustrates an array of scopes. Whereas in this array, you can also find the value that is accessible to the client when consenting.

{
  "logged_in": false,
  "validation_type": "scope_consent",
  "meta_data": {
    "amr_values": [
      "10"
    ],
    "scopes": [
      {
        "scope": "contract",
        "status": "OPEN"
      }
    ]
  },
  "used": false
}

It returns an array of scopes as scope which is required as input for the Step 3.

Step 3: Accepting the scope

To accept scope consent, you can use a POST-call to provide all scope keys from the metadata, as well as the masked sub and the client_id returned in the redirection.

curl 'https://demo.cidaas.de/consent-management-srv/consent/scope/accept' \
  -X 'POST' \
  --data-raw '{"sub":"b05b5498-a8f2-4cf4-89b9-bd2fc0b5e13b","client_id":"69d81af1-e4f6-4062-8754-9ee5752a7ca4","scopes":["contract"]}' \
  --compressed

Step 4: Continue the login Process

The final call will allow you to issue a token or code, depending on the grant you are using. It will again verify if all required consents are provided. If the fulfillment was not successful and the user has not accepted the required scope, they will again end up on the scope consent page.

curl 'https://qc-v3.cidaas.de/login-srv/precheck/continue/958ccb4c-3985-4b17-b325-14cd10da292e' \
  -X 'POST' \
  --compressed

Developer Perspective

API	Description	Link
GET Pre-Login Metadata	This API will provide you with information about which user interaction is required to be completed, e.g., which consent is missing. It is mostly required for requests for user consent or user information, with no other conditions.	View API
POST Accept Scope Consent	To accept the scope consents that were requested and determined to be required for this authentication process.	View API
POST Continue Login	To continue the login so that a code or token is issued, the continue API call will proceed.	View API

Implementation using SDKs

This Implementation Guide is based on the default hosted pages which uses an Angular framework based on Typescript. It can be implemented in any other programming language as well.

As a first step you will be redirected to the consent_scopes page. This section starts to show the APIs to be called when reaching this page:

To install the cidaas-sdk please perform the following command.

npm install cidaas-javascript-sdk

The import to your webapp will be done by using:

this.cidaas_sdk = new WebAuth(options)

Step 1: Retrieving the Missing Scopes using Token Prelogin Metadata

    const resp = await this.cidaas_sdk.getScopeConsentDetails({
      track_id: this.route.snapshot.queryParams['track_id'],
      locale: navigator.language,
      requestId: this.route.snapshot.queryParams['requestId'],
});

Using the response of this API call, you can render the UI as displayed above. It will present the scope key as well as you are able to present the values which are able to be requested during the userinfo or even provided in the id_token.

Step 2: Accepting the scope

To finally proceed with the authentication process and be able to use your service, the user must click on the accept button. The final call will accept the scope consent by providing all scope keys which you received from the above request to the below request body (scopesArray).

      const resp = await this.cidaas_sdk.acceptScopeConsent({
        sub: this.route.snapshot.queryParams['sub'],
        client_id: this.route.snapshot.queryParams['client_id'],
        scopes: scopesArray
      });

Step 3: Continue the login Process

The scopeConsentContinue will continue the login process and finally the user will be redirected to the provided redirect_uri.

    const resp = await this.cidaas_sdk.scopeConsentContinue({
      sub: this.route.snapshot.queryParams['sub'],
      client_id: this.route.snapshot.queryParams['client_id'],
      track_id: this.route.snapshot.queryParams['track_id'],
    });

Explore Related Topics

• Login Success
• Group Selection
• Communication Verification

---

Need help implementing this?

Please contact us on our Developer Support Page.