Authorization Endpoint
To begin the Interac Hub ID verification process, the relying party directs the user's web browser to send an HTTP GET request (via the URL bar) to the Hub API's authorization_endpoint.
GET /auth?
request=val1&response_type=val2&client_id=val3&scope=val4&state=val5&redirect_uri=val6
Host: hub_server.example.com
This consists of the authorization_endpoint URL followed by a query string with several parameters:
| REQUIREMENT | PARAMETER | EXAMPLE VALUE | DESCRIPTION |
|---|---|---|---|
| Required | request | eyJhbGciOiJSUzI....huQkaQ | Signed Request Object A request object in a signed JWT (JWS) compact-serialized format. Refer to RFC 7519 JSON Web Tokens and RFC 7515 JWS compact serialization. This JWS must be signed by the RP using the private portion of an RSA keypair. The public portion is the one published to the RP's JWKS endpoint and registered with the Hub during onboarding (via the RP's JWKS URL). A number of parameters need to be included in this JWS and are detailed in the subsequent table. |
| Required | response_type | code | Always set to code to indicate an authorization code grant flow. |
| Required | client_id | hub-int-team | The OAuth 2.0 client ID provided during onboarding unique to the RP/DAC |
| Required | scope | openid onlyVme | A space-delimited list of OIDC scopes defined for the RP/DAC during onboarding. |
| Optional | state | bee48cf1eb0c40ec817df458e0cb4cb6 | A unique and random identifier generated by the RP/DAC for each Hub transaction. This value will be included for any Hub responses to the HTTP GET authorization_endpoint call (via the RP's redirect_uri) such as delivery of the authorization code or error messages. Mandatory user state tracking: An RP/DAC must match track the generated state value against an internal user to confirm that the authorization code returned by the Hub is for the expected user. Not tracking the state value introduces the possibility that the RP mismatches the authorization code intended for a user with another user and retrieves the incorrect user claims. |
| Required | redirect_uri | http://localhost:5000/loginResponse | The URL hosted by the RP/DAC where Hub will return the authorization code to via a user browser redirect. This URL must be registered during onboarding. |
Signed Request Object header: The request JWT object parameter contains the signed request object. This is a signed JWT (JWS) signed with the RP's private key in compact serialized format. The signed request object header contains the following parameters.
| REQUIREMENT | PARAMETER | EXAMPLE VALUE | DESCRIPTION |
|---|---|---|---|
| Required | alg | RS256 | Always RS256 to indicate the algorithm used. |
| Required | kid | cIlDeR8D4RexrZmUdKhBxMsD2bMX4l87_5JrARh4VIU | The kid (key ID) parameter of the signing key must be provided in the JOSE Header of the signed request object to indicate to the Hub which of the RP keys to be used to validate the signature. |
Signed Request Object parameters: The request JWT object parameter contains the signed request object. This is a signed JWT (JWS) signed with the RP's private key in compact serialized format. The signed request object payload includes several parameters (a number of which are identical to the parameters in the authorization_endpoint query string).
| REQUIREMENT | PARAMETER | EXAMPLE VALUE | DESCRIPTION |
|---|---|---|---|
| Optional | code_challenge | auLKHU3iYYApyCx7WQU9C_yEWVys5q2D1J3B6phV1Ms | A SHA-256 hash of the PKCE code verifier string, used to mitigate CSRF and injection attacks. |
| Optional | code_challenge_method | S256 | This will always be set to S256 if PKCE code challenge/verifier is used to indicate the code challenge is a SHA-256 hash. |
| Required | redirect_uri | http\://localhost:5000/loginResponse | (Same as request parameter) The URL hosted by the RP/DAC where Hub will return the authorization code to via a user browser redirect. This URL must be registered during onboarding. |
| Optional | client_id | hub-int-team | (Same as request parameter) The OAuth 2.0 client ID provided during onboarding unique to the RP/DAC |
| Required | scope | openid onlyVme | (Same as request parameter) A space-delimited list of OIDC scopes defined for the RP/DAC during onboarding. |
| Required | iss | hub-int-team | Identifies the RP/DAC issuing the request. This must be the same as the client_id. |
| Required | aud | https://gateway-devportal2.pp.vids.dev | Identifies the service to which the request is being sent. This must be the issuer value as defined in the Hub's openid-configuration endpoint. |
| Required | response_type | code | (Same as request parameter) Always set to code to indicate an authorization code grant flow. |
| Required | state | 5de789881cc944a78e9c1c9d947f7867 | (Same as request parameter) A unique and random identifier generated by the RP/DAC for each Hub transaction. When the authorization code is returned from the Hub to the RP, the state value will also be returned and must be matched by the RP to ensure the right code is being used for the right transaction |
| Optional | nonce | abdd5eed89834b62aee2de7a6ed4d92e | A random value generated by the RP/DAC to mitigate replay attacks. The nonce value is treated as an opaque value by the authorization server and is returned unchanged in the ID Token. |
| Optional | ui_locales | en-CA | A space delimited list of locale strings as described in RFC 5646. If provided, this will be used to select the initial language in the Hub service and web client. Interac® verification service mobile clients are not affected by this. The language may be changed in HUB UI. The final language used in the HUB web client will be returned in the com.securekey.verified.me.ui_locale claim from the UserInfo endpoint. Available values: en-CA, fr-CA |
| Optional | subject | { "given_name": "John", "family_name": "Doe", "address": { "postal_code": "M2P 1N6" }, "birthdate": "1965-03-03" } | This is only to be included if subject matching has been enabled for your client ID. This is a JSON object containing the user details that the RP/DAC currently has on file, to be sent to the Hub to match against the user claims received from the bank or doc scanning engine. The fields available to be matched depend on the ruleset provisioned as part of the onboarding process (e.g. "default_KYC"). Refer to the rulesets for detailed matching rule definitions (KB article, access restricted). |
Referenced Standard(s):RFC 6749: The OAuth 2.0 Authorization Framework (4.1. Authorization Code Grant), RFC 9101: The OAuth 2.0 Authorization Framework: JWT-Secured Authorization Request (JAR), OpenID Connect Core 1.0 (3.1.2.1. Authentication Request)
Example Request / Response
https://gateway-devportal2.pp.vids.dev/auth?request=eyJhbGciOiJSUzI1NiIsImtpZCI6ImNJbERlUjhENFJleHJabVVkS2hCeE1zRDJiTVg0bDg3XzVKckFSaDRWSVUifQ.eyJhdWQiOiJodHRwczovL2dhdGV3YXktZGV2cG9ydGFsMi5wcC52aWRzLmRldi8iLCJjbGllbnRfaWQiOiJodWItaW50LXRlYW0iLCJjb2RlX2NoYWxsZW5nZSI6ImF1TEtIVTNpWVlBcHlDeDdXUVU5Q195RVdWeXM1cTJEMUozQjZwaFYxTXMiLCJjb2RlX2NoYWxsZW5nZV9tZXRob2QiOiJTMjU2IiwiaXNzIjoiaHViLWludC10ZWFtIiwibm9uY2UiOiJhYmRkNWVlZDg5ODM0YjYyYWVlMmRlN2E2ZWQ0ZDkyZSIsInJlZGlyZWN0X3VyaSI6Imh0dHA6Ly9sb2NhbGhvc3Q6NTAwMC9sb2dpblJlc3BvbnNlIiwicmVzcG9uc2VfdHlwZSI6ImNvZGUiLCJzY29wZSI6Im9wZW5pZCBvbmx5Vm1lIiwic3RhdGUiOiI1ZGU3ODk4ODFjYzk0NGE3OGU5YzFjOWQ5NDdmNzg2NyIsInVpX2xvY2FsZSI6ImVuLUNBIn0.rBmjM6KEYsoBCoR2Wk3XnAP57AVqVo-gG4BdQp1wVZs4GiD77Oo9JTYvOZXyk1qmdttxkMUUo8Uj5ibAmsV0kY4-56mdAOuLryBYVRpwmVAWIgJ7I49LItNDnRbOhSyJkUsXUUFu85am27r83XoTjm5xIHYzfFCsNoBVD0oDsuFDZX8ri6UY7vK3Y9feIBqPYXERmuBsDohwogyZbXEUe0AbHFmdcYyYVcLY5q1mSF_0VBqZIsRiC73sipohhGkWy0No-oArTshKZ5C_BWxpCoTxCiS8xvz6wffmyJBqKbOjPYKmRD59BZ6yRysXzbShsFaezw_MwsRaMWfFMnrT3A&response_type=code&client_id=hub-int-team&scope=openid+onlyVme&state=5de789881cc944a78e9c1c9d947f7867&redirect_uri=http%3A%2F%2Flocalhost%3A5000%2FloginResponse
- request=eyJhbGciOiJSUzI1NiIsImtpZCI6ImNJbERlUjhENFJleHJabVVkS2hCeE1zRDJiTVg0bDg3XzVKckFSaDRWSVUifQ.eyJhdWQiOiJodHRwczovL2dhdGV3YXktZGV2cG9ydGFsMi5wcC52aWRzLmRldi8iLCJjbGllbnRfaWQiOiJodWItaW50LXRlYW0iLCJjb2RlX2NoYWxsZW5nZSI6ImF1TEtIVTNpWVlBcHlDeDdXUVU5Q195RVdWeXM1cTJEMUozQjZwaFYxTXMiLCJjb2RlX2NoYWxsZW5nZV9tZXRob2QiOiJTMjU2IiwiaXNzIjoiaHViLWludC10ZWFtIiwibm9uY2UiOiJhYmRkNWVlZDg5ODM0YjYyYWVlMmRlN2E2ZWQ0ZDkyZSIsInJlZGlyZWN0X3VyaSI6Imh0dHA6Ly9sb2NhbGhvc3Q6NTAwMC9sb2dpblJlc3BvbnNlIiwicmVzcG9uc2VfdHlwZSI6ImNvZGUiLCJzY29wZSI6Im9wZW5pZCBvbmx5Vm1lIiwic3RhdGUiOiI1ZGU3ODk4ODFjYzk0NGE3OGU5YzFjOWQ5NDdmNzg2NyIsInVpX2xvY2FsZSI6ImVuLUNBIn0.rBmjM6KEYsoBCoR2Wk3XnAP57AVqVo-gG4BdQp1wVZs4GiD77Oo9JTYvOZXyk1qmdttxkMUUo8Uj5ibAmsV0kY4-56mdAOuLryBYVRpwmVAWIgJ7I49LItNDnRbOhSyJkUsXUUFu85am27r83XoTjm5xIHYzfFCsNoBVD0oDsuFDZX8ri6UY7vK3Y9feIBqPYXERmuBsDohwogyZbXEUe0AbHFmdcYyYVcLY5q1mSF_0VBqZIsRiC73sipohhGkWy0No-oArTshKZ5C_BWxpCoTxCiS8xvz6wffmyJBqKbOjPYKmRD59BZ6yRysXzbShsFaezw_MwsRaMWfFMnrT3A
JWT header decoded:
{
"alg": "RS256",
"kid": "cIlDeR8D4RexrZmUdKhBxMsD2bMX4l87_5JrARh4VIU"
}
JWT body decoded:
{
"aud": "https://gateway-devportal2.pp.vids.dev/",
"client_id": "hub-int-team",
"code_challenge": "auLKHU3iYYApyCx7WQU9C_yEWVys5q2D1J3B6phV1Ms",
"code_challenge_method": "S256",
"iss": "hub-int-team",
"nonce": "abdd5eed89834b62aee2de7a6ed4d92e",
"redirect_uri": "http://localhost:5000/loginResponse",
"response_type": "code",
"scope": "openid onlyVme",
"state": "5de789881cc944a78e9c1c9d947f7867",
"ui_locale": "en-CA"
}
- response_type=code
- client_id=hub-int-team
- scope=openid+onlyVme
- state=5de789881cc944a78e9c1c9d947f7867
- redirect_uri=http%3A%2F%2Flocalhost%3A5000%2FloginResponse
When the Customer completes the verification process (bank authentication flow and/or document scanning flow), the Interac Hub returns the user's web browser to the whitelisted redirect_uri initially provided in the authorization call.
The successful response has the following query parameters:
- code: The authorization code to use in the token exchange for an access token.
- state: The state provided in the authorization request. Internal mapping of the state value can be used for session tracking of the end-user. The RP should be tracking state to confirm that the returned code and subsequent calls to the Hub token_endpoint and userinfo_endpoint pertain to the correct user on the RP side.
- scope: The OIDC scope provided in the authorization request.
http://localhost:5000/loginResponse?code=5GT81abUDETEOpVegWBZ78AejqElS-atMzTNF_7UQYQ.IfKMxHcxM5PdoDtQyNhXl5jb8uS5lxs1xc-hQHRcR8Q&scope=openid+onlyVme&state=5de789881cc944a78e9c1c9d947f7867
- code=5GT81abUDETEOpVegWBZ78AejqElS-atMzTNF_7UQYQ.IfKMxHcxM5PdoDtQyNhXl5jb8uS5lxs1xc-hQHRcR8Q
- scope=openid+onlyVme
- state=5de789881cc944a78e9c1c9d947f7867
- If the user starts the flow on a non-default browser on a mobile device and uses the Interac® verification service mobile app to consent for the data share, then the Interac® verification service the mobile app will proceed to open the default browser on the device and the response will appear from the default browser (Example on iOS: Chrome --> Interac® verification service mobile app --> Safari).
- If the user starts the Interac® verification service mobile application on a mobile device by scanning QR-code on the desktop and then closes the original desktop browser window before completing the request, the Interac® verification service mobile app will open RP’s page in the default mobile browser.
Updated about 1 year ago