Authorization Code Grant
This authentication method is based on the Oauth2 Authorization Code Grant method.
The authorization code grant type is used to obtain both access tokens and refresh tokens and is optimized for confidential clients. Since this is a redirection-based flow, the client must be capable of interacting with the resource owner's user-agent (typically a web browser) and capable of receiving incoming requests (via redirection) from the authorization server.
Authorization Request
The first step for the Client application is to notify the user (resource owner) that the application needs access to the users ImageVault application. The notification will display a information screen that informs the user and asks the user to either Deny or Allow access to ImageVault.
To display the dialog you need to access a page in the ImageVault UI and pass along the following query string parameters.
| Parameter Name | Description |
|---|---|
| response_type | Defines the type of grant to be requested. Must be set to "code". |
| client_id | The id of the client application that requests access to ImageVault (See OAuth Clients) |
| redirect_uri | [Optional] The uri where the response should be redirected. If omitted, the clients registered redirect_uri will be used. |
| state | RECOMMENDED. An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter SHOULD be used for preventing cross-site request forgery as described in Section 10.12. |
Example:
GET /oauth/authorize?response_type=code&client_id=myApplication&redirect_uri=https%3a%2f%2fmyserver.com HTTP/1.1
Host: imagevault.ui.server.com
Authorization Response
If the resource owner grants the access request, the authorization server issues an authorization code and delivers it to the client by adding the following parameters to the query component of the redirection URI using the "application/x-www-form-urlencoded" format, per Appendix B:.
| Parameter Name | Description |
|---|---|
| code | REQUIRED. The authorization code generated by the authorization server. The authorization code MUST expire shortly after it is issued to mitigate the risk of leaks. A maximum authorization code lifetime of 10 minutes is RECOMMENDED. The client MUST NOT use the authorization code more than once. If an authorization code is used more than once, the authorization server MUST deny the request and SHOULD revoke (when possible) all tokens previously issued based on that authorization code. The authorization code is bound to the client identifier and redirection URI. The code consists of a up to 30 characters case sensitive string. |
| state | REQUIRED if the "state" parameter was present in the client authorization request. The exact value received from the client. |
| url | The url for the Core service endpoint that accepts Access token requests. (see below) |
For example, the authorization server redirects the user-agent by sending the following HTTP response:
HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz&url=https%3a%2f%2fimagevault.core.server.com
Error response
If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
If the resource owner denies the access request or if the request fails for reasons other than a missing or invalid redirection URI, the authorization server informs the client by adding the following parameters to the query component of the redirection URI using the "application/x-www-form-urlencoded" format, per Appendix B:
The parameter description for the error response can be found in the 4.1.2.1 Error response section.
For example, the authorization server redirects the user-agent by sending the following HTTP response:
HTTP/1.1 302 Found Location: https://client.example.com/cb?error=access_denied&state=xyz
Access token request
When you have retrieved the authorization token you can use this to request an access token and a request token. This is done by sending the following parameters using the "application/x-www-form-urlencoded" format per Appendix B with a character encoding of UTF-8 in the HTTP request entity-body:
| Parameter Name | Description |
|---|---|
| grant_type | REQUIRED. Value MUST be set to "authorization_code". |
| code | REQUIRED. The authorization code received from the authorization server. |
| redirect_uri | REQUIRED, if the "redirect_uri" parameter was included in the authorization request as described in Section 4.1.1, and their values MUST be identical. |
The client MUST authenticate with the client credentials using HTTP basic authentication.
The access token request MUST be directed to the /apiv2/oauth/token resource of the url that was returned from the Authorization response.
For example, the client makes the following HTTP request using TLS (with extra line breaks for display purposes only):
POST /apiv2/oauth/token HTTP/1.1
Host: imagevault.core.server.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
Access token response
If the access token request is valid and authorized, the authorization server issues an access token and an refresh token as described in Resource owner password credential grant, Access token response If the request client authentication failed or is invalid, the authorization server returns an error response as described in Section 5.2.
The refresh-token allows the client application to request a new access token without prompting the user again.