Remote consent protocol

The Remote Consent Protocol is embedded in the OAuth 2.0 Authorization Code Grant Flow and begins after the end-user has been authenticated it-self in IAM.

The following parties are involved:

Party

OAuth 2 Concept

Authorization Code Flow

Remote Consent Protocol

End-User (Browser)

User-Agent

check.svg

Third-Party Application

Client

check.svg

Airlock IAM

Authorization Server (AS)

check.svg
check.svg

Remote Consent Application

-

check.svg
check.svg
112231400.png

The Remote Consent Flow (green) is embedded in the OAuth 2.0 Authorization Code Flow (blue) such that it can be executed instead of displaying the IAM's consent page.

The Remote Consent Protocol (green) is as follows:

  • (3) After the end-user has been authenticated: IAM redirects the end-user's browser to the Remote Consent Application.

    • With the redirect, IAM sends the following HTTP GET parameters:

    • "consent_token": an encrypted and signed JWT bearing the following claims:
      • sub: The name of the authenticated end-user (IAM-internal username - not necessarily the same as the user entered when logging in).
      • scope: The scopes as requested by the OAuth client (JSON array).
      • consent_nonce: A nonce for this remote consent flow.
      • callback_uri: The Remote Consent Application must redirect the end-user's browser to this URI after consent.
      • exp: expiry date  (registered claim according to RFC7519)
        • The token lifetime is configurable in IAM.
        • The Remote Consent Application must not accept expired tokens.
      • iat: issue timestamp (registered claim according to RFC7519)
        • If the issue timestamp lies in the future, the token must be considered invalid by the Remote Consent Application.
      • client_id: The client id of the OAuth2 client.
    • "lang": contains the two-letter language code (e.g. "en", "de", "fr") of login page display language. This is the language the end-user chose to log in with. Example Redirect URL (not URL-encoded)
      • /ebanking/display-consent?lang=de&consent_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVC... (JWT truncated)
  • (4) The end-user interacts with the Remote Consent Application to give the consent: The Remote Consent Application reads and verifies the JWT "consent_token" to display the consent screen to the end-user.
  • (5) The Remote Consent Application redirects the end-user's browser back to the callback_uri and puts an encrypted and signed JWT as GET parameter consent_token in the HTTP redirect. 
  • The JWT bears the following claims:
    • consent_given: true or false. Indicates whether the user gave consent or not.
    • scope: The scopes accepted by the end-user (JSON array). May be empty. Must be empty if consent_given is false.
    • consent_nonce: The nonce as received in the JWT "consent_token". Example Redirect URL (not URL-encoded - AS-centric):
      • /auth/oauth2/v3/confirm-consent?consent_token=eyJhbGciOiJIUzI1NiIsInR5c... (JWT truncated)

      Note: 

      • Airlock IAM writes the JWT to the audit log file.
      • If no JWT is present or the JWT cannot be validated, the OAuth 2.0 flow is aborted in Airlock IAM.
  • (6) Airlock IAM verifies the JWT from the Remote Consent Application
    • If consent_given=true: Authorization Code flow continues in Airlock IAM.
    • If consent_given=false: The remote consent is aborted, no authorization_code is issued.