VerifID Integration
Verification request and response
Verification request
To initiate Verification, the Client shall issue a request which is an Authorization Request(3) per the OAuth 2.0 specification. This request takes the form of redirecting the User’s browser to VerifID’s “authorization_endpoint” with a query string of the following format:
https://example.edu/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URL&scope=verify:student&state=STATE
Required parameters:
| Parameter | Definition |
|---|---|
response_type |
The fixed string “code” (without quotes). |
client_id |
The unique Client identifier assigned during registration. |
redirect_uri |
A callback URL for the Verification response to be delivered. This must be one of the URLs stored with the
Client registration. We require redirect_uri values to be encoded according to RFC 3986, Section 2.1. This is commonly known as percent or URL encoding. Not using this encoding method may result in HTTP 403, resource forbidden, errors. |
scope |
A space-separated list of scopes requested for Verification. The supported values for VerifID
are:
The scope verify:* is interpreted specially by VerifID, and is expanded to all verification types
granted to the client. When requesting this scope, the verification response will indicate the true set of scopes
that are granted.
Other scopes may be listed among the supported scopes in the authorization server metadata. These are not described in this document and not required for VerifID integration. |
state |
An identifier which the Client provides to uniquely identify the Verification request they have initiated. It is recommended that the Client use this to relate request to response and prevent cross-site request forgery. The value must be unique and securely random, and shall be stored by VerifID for auditing purposes. Non-unique values shall be rejected by VerifID and will result in failed Verification requests. The value must be at least 16 characters, and must not exceed 128 characters in length. It must consist of only letters, numbers, hyphens (-) and underscores (_). |
A suggested method of generating a suitable state value is: Generate 60 random bytes using a cryptographically secure PRNG; and then Encode those bytes using the URL-safe Base64 encoding scheme.
Optional parameters:
| Parameter | Definition |
|---|---|
entity_id |
A preselected SAML Identity Provider provided by the Client which will be used to authenticate the User. If this value is provided, it is the responsibility of the Client to ensure the value represents a valid IdP which is known to VerifID. The presence of this value will skip the SAML Discovery Service when performing federated authentication. We require entity_id values to be encoded according to RFC 3986, Section 2.1. This is commonly known as percent or URL encoding. Not using this encoding method may result in HTTP 403, resource forbidden, errors. |
Verification response
After authenticating to their Organisation via the VerifID Service Operator federation, the result of Verification will be a “protected resource”(4) as described in the OAuth 2.0 specification. An authorization response shall be returned by redirecting the User’s browser to the Client’s redirect_uri, with query parameters:
[redirect_uri]?code=AUTHORIZATION_CODE&
scope=verify:student&state=STATE
The parameters shall be completed as follows:
| Parameter | Definition |
|---|---|
code |
The authorization code which shall be used to gain an access token for access to the Verification result. The value shall not exceed 128 characters in length. |
scope |
The list of scopes which have been granted for Verification. Clients must allow for a space-separated list
of values to be returned here per the OAuth 2.0 specification, even if they only anticipate receiving a single scope.
The verify:* scope will not appear in this list. If it was requested, it will instead be
expanded to the true set of scopes that are granted. |
state |
The state value which the Client provided in the Verification request. |