Resource Owner Password Credentials Grant

This authentication method is based on the Oauth2 resource owner password credentials grant method.

The resource owner password credentials grant allows a client to authenticate using the resource owner credentials. To use this grant both a client credential set and a resource owner credential set must be used.

The client credential can be retrieved from Meriworks and must be activated by an administrator for the ImageVault installation that the client should be able to connect to.

The resource owner credentials is the username/password that a user uses to authenticate to accesss ImageVault.

Access token request

The client first requests an access token from the core server by providing user credentials using HTTP basic authentication. The user name/password to supply is the client identity that is registered in ImageVault Core. See creating client identities for more information.

Note: You can also request a client identity from Meriworks for embedding in your application.

You also need to supply the username and password of the resource owner. The following parameters must be supplied.

Parameter NameDescription
grant_typeDefines the type of grant to be requested. Must be set to "password".
usernameThe resource owner username
passwordThe resource owner password

Every parameter is provided as urlencoded form data (application/x-www-form-urlencoded)

Example

For example, the client makes the following HTTP request using transport-layer security (with extra line breaks for display purposes only):

POST /apiv2/oauth/token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=johndoe&password=A3ddj3w

Access token response

If authentication is successful and all parameters are valid, then the service will return an access token on JSON format. The access token contains the following properties

Parameter NameDescription
access_tokenContains the access token itself.
token_typeThe type of token that was issued.
expires_inThe number of seconds that this token is valid
refresh_token[Optional] The refresh token, which can be used to obtain new access tokens.

Example

An example successful response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"Bearer",
  "expires_in":3600,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
}

Further request

The received access token can then be used in coming requests to the core service until the token has expired. The access token is passed along using the Authorization (or IVAuthorization) http request headers. The value of the header is the token_type followed by a whitespace and then the access_token itself.

Example

The following example shows the usage of the Authorization header.

POST https://imagevault.local/apiv2/MediaService/Find HTTP/1.1
Host: imagevault.local:8001
Content-Length: 2
Cache-Control: no-cache
Pragma: no-cache
Authorization: Bearer irlfrfq4x32uh20xji6w
Content-Type: application/json; charset=UTF-8

{}

Refreshing an access token

If the authorization server issued a refresh token to the client, the client makes a refresh request to the token endpoint by adding the following parameters as urlencoded form data (application/x-www-form-urlencoded).

Parameter NameDescription
grant_typeDefines the type of grant to be requested. Must be set to "refresh_token".
refresh_tokenThe refresh token issued to the client.

Example

For example, the client makes the following HTTP request using transport-layer security (with extra line breaks for display purposes only):

POST /apiv2/oauth/token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

Because refresh tokens are typically long-lasting credentials used to request additional access tokens, the refresh token is bound to the client to which it was issued.

The response from an Refresh token request is the same as an ordinary access token response.

The authorization server MAY issue a new refresh token, in which case the client MUST discard the old refresh token and replace it with the new refresh token. The authorization server MAY revoke the old refresh token after issuing a new refresh token to the client.

comments powered by Disqus
+46 (0)480 - 31 47 95
info@imagevault.se
Swedish website