Skip to content
GitHub

Grant Interaction Flow

Sequence Diagram

Sequence diagram View full image

Endpoints

If the AS deems interaction necessary to issue a grant, there are five main endpoints that are used once a pending grant has been created. In each endpoint, the specific interaction is identified with an interaction id and an interaction nonce. Both of these are provided in the query parameters of the URL when the authorization server redirects to the Identity Provider. The endpoints, in order of their calling, are as follows:

  • GET /interact/:id/:nonce (made by the client to the AS, establishes an interaction session, redirects browser session to IDP consent screen)
  • GET /grant/:id/:nonce (made by the IDP to the AS, secured with x-idp-secret header, returns grant info for the consent screen to enumerate )
    • This is served on INTERACTION_PORT and its default value is 3009
  • POST /grant/:id/:nonce/(accept OR reject) (made by the IDP to the AS, secured with x-idp-secret header, accepts or rejects the grant based on the user’s input on the consent screen. IDP then redirects to GET /interact/:id/:nonce/finish)
    • This is served on INTERACTION_PORT and its default value is 3009
  • GET /interact/:id/:nonce/finish (ends the interaction established by GET /interact/:id/:nonce, redirects browser session to client callback. Contains a query param that either indicates a failure, or on success, a hash parameter that the client can use to verify the successful interaction, and the interact_ref that identifies the interaction on the AS.)
    • Examples include: - ?result=grant_rejected (if interaction was rejected) - ?result=grant_invalid (if grant is not in a state where it may be accepted or rejected, e.g. already approved) - ?hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R\HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A &interact_ref=4IFWWIKYBC2PQ6U56NL1 (if interaction was accepted) - hash is a sha-256 hash of values provided by the client in the body of the grant initialization request (interact.finish.nonce), values returned in the AS response for that request (interact.finish), the interact_ref provided alongside the hash, and the uri of the grant initialization request (https://auth-server.com/).
  • POST /continue/:id (this should still be accurate, final back-channel request made by client if interaction was successful, AS responds with an access token)

On x-idp-secret

x-idp-secret is the name of a header that is used for GET /grant/:id/:nonce, POST /grant/:id/:nonce/accept, and POST /grant/:id/:nonce/reject requests. Its purpose is to secure communications between the IDP and the AS and its value should be a shared secret known to both entities.

To set this up, set the IDENTITY_SERVER_SECRET on the AS environment to a value that is also used to configure the IDP’s requests to the AS.