Versions Compared

Old Version 7

changes.mady.by.user Viktor Kisko

Saved on

compared with

New Version 8

changes.mady.by.user Viktor Kisko

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

The client-side flow is optimised for public clients such as pure HTML5/JavaScript clients.

Note
titleCheck if valid
In fact,

...

Keycloack does not permit a confidential client to use this flow (non-standard?).

The client directs the end user's browser (e.g. in a pop-up window or IFRAME) to the authorization endpoint with the following query parameters added ("application/x-www-form-urlencoded" format) to the endpoint URI:

...

access_token: The access token issued by ArchieKeycloack.

token_type: Always "Bearer" in Archie's implementation .

expires_in: The number of seconds that the token is valid.

...

In case of an error condition, depending on the error type, an error message will either be displayed directly to the end user (if there is a problem with the client ID or redirect URI), or it will be provided as an error parameter in the fragment component of the redirect URI to the client. See the specification section 4.2.2.1 for details.for details.

Resource Owner Password Credentials

The Resource Owner Password Credentials flow allows client to obtain an access token using resource owner's credentials (username and password). The Password grant is one of the simplest OAuth grants and involves only one step: client uses resource owner's username and password to make POST request to the server to exchange password for access token.  This authorization grant type requires that the application collect the user’s password.

POST request is done with follwoing parameters:

grant_type (required): Must be set to "password" for this flow.

username(required): Must be set to resource owner usrename.

password(required): Must be set to resource owner password.

client_id(required): Must be set to identifier of the client that was obtained during client registration.

scope (optional): The scope of the resources that the access token should provide access to. Possible values are:

  • "none": The default, single sign on only, no access to data

  • "person: Manage person records

  • "group": Manage groups

  • "document": Manage documents and reviews

  • "workflow": Manage tasks and workflows

  • "crs": Manage studies in CRS

  • "crso": Manage studies in CRSO

  • "linked_data": Access to linked data resources

  • "all": Manage any resource type


Access Code Response

The response to the POST request is a JSON object (MIME type "application/json") like this:

{
    "access_token": "3e8ec1a3d43c983b57df0616b498c04807b466e919999aa0f3f3aabca1dd48cc",
    "token_type": "Bearer",
    "expires_in": "14400"
}

Client Credentials Grant flow

The client credentials flow allows a confidential client (server) to obtain an access token server-to-server without involving an end user. Before this flow is used, an Archie Keycloack user must be associated with the client. The access token obtained with this flow will be associated with the user and the user's permissions.

...

For further details see section 5.2 of the specification.


Note
titleShould this be removed?

Validating the access token (non-standard)

Archie provides a mechanism for validating and obtaining information about an access token. If the OAuth 2.0 authorization framework is used for single sign on only by a public client it is important to validate the token to ensure that the request to the redirect URI is genuine. 

To validate a token, make a GET or POST request to the token information endpoint (see above) with the following query parameters included:

access_token (required): The token to be validated. This can also be provided in the Authorization header in the form: Bearer [access token] 

include_permissions (optional):  Value can be "true" or "false" (default). Specifies whether the response should include information about the end user's Archie permissions within the scope of the access token.

detailed (optional):  Value can be "true" or "false" (default). Specifies whether the response should include the following information in the response: user_id, name (combined), first_name, last_name and email.

The response is a JSON object (MIME type "application/json") like this:

{
    "user_name": "testuser",
    "scope": "document",
    "expires_in": "2410",
    "client_id": "my_account",
    "person_id": "11143"
}

Use person_id as a user's stable ID

Note that the user_name for a given user may change over time, e.g. if the user's email changes, and if the user account is closed it may be reused later by another account. If you need an immutable identifier that will not be reused, person_id is recommended.

Or, with both detailed=true and include_permissions=true:

{
    "user_name": "testuser",
    "scope": "person",
    "expires_in": "3192",
    "client_id": "my_account",
    "person_id": "11143",
    "user_id": "08573771072139469457090803092242",
    "name": "Test User",
    "first_name": "Test",
    "last_name": "User",
    "email": "test-user@cochrane.org",
    "permissions": [
        {
            "resource": "person",
            "entity": "D37BDF5182E26AA2013C72096D0CE6B1",
            "grants": ["view", "view_private", "write"]
        }
    ]
}


In case of an error condition the response will follow the same structure as for the token endpoint (see above).


Refreshing an access token

...

In case of an error condition, e.g. if the refresh token is no longer valid, the response will follow the same structure as for other token endpoint errors. The client should discard the refresh token and obtain a new access token using the server-side flow.

Note
titleShould this be removed?

Revoking an access token (non standard)

An access token can be revoked/invalidated by making a GET or POST request to the token revoking endpoint (see above) with a single parameter:

access_token (required): The token to be revoked.

In case of an error condition the response will follow the same structure as for the token endpoint (see above).

For security reasons public clients are adviced to revoke any tokens that are no longer being used, e.g. when the user logs out of the application.


Using an access token to access the API

The access token must be passed to the API in the Authorization header, e.g.:

GET https://archie.cochrane.org/rest/reviews/CD000004 HTTP/GET ???  HTTP/1.1

Authorization: Bearer 3e8ec1a3d43c983b57df0616b498c04807b466e919999aa0f3f3aabca1dd48cc

...

As another example, the API contains a method to get the user's permissions for a single review:

GET https://archie.cochrane.org/rest/reviews/CD000004/permissionsGET ??? HTTP/1.1

Authorization: Bearer 3e8ec1a3d43c983b57df0616b498c04807b466e919999aa0f3f3aabca1dd48cc

...