Skip to content
This repository has been archived by the owner on May 2, 2024. It is now read-only.

Latest commit

 

History

History
242 lines (167 loc) · 9.38 KB

oauth2.md

File metadata and controls

242 lines (167 loc) · 9.38 KB
Raw

Description of oAuth2 login flow.

This is documentation for how to implement login.bib.dk using an oAuth2 authorization flow.

1. Authorization

Login.bib.dk implements two different grant types that can be used for authorization. "Authorization Code Grant" and "Password Grant". If possible the "Authorization Code Grant" flow should used.

1.1. Authentication Code Grant

This describes how login.bib.dk implements the "Authorization Code Grant" as specified in https://tools.ietf.org/html/rfc6749#section-4.1.

1.1.1. Make redirect to https://login.bib.dk/oauth/authorize

Authorization Request

See https://tools.ietf.org/html/rfc6749#section-4.1.1

The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI:

  • response_type: Must be set to code. Indicates that the client expects to receive an authorization code (required).
  • client_id: client ID (required).
  • redirect_uri: URI to be returned to when user authorization has been completed. Must be configured in the access platform (required).
  • scope: is not implementet. If specified it is just discarded.
  • state: A hash generated by the client application, used by the application to verify the validity of the return call (optional). https://login.bib.dk/oauth/authorize?response_type=code&clientId={CLIENT_ID}&redirection_uri={REDIRECTION_URI}&state={SOME_STATE_HASH}

Custom parameters

There are also the following non standard oauth parameters, that can be used in the login flow:

  • presel: A preselected Agency ID that can be changed by the user (optional)
  • agency: A preselected Agency ID that can NOT be changed by the user (optional)
  • ipd: Force login through the specified identityprovider (nemlogin | borchk) (optional)
  • agencytype: list of agencytypes that should be in libary dropdown. Possible values, folk: folkebiblioteker, forsk: forskningsbiblioteker (optional).
  • force_login: Set to force the user to login and ignore a possible SSO possibility (0 | 1) (optional). https://login.bib.dk/oauth/authorize?response_type=code&clientId={CLIENT_ID}&redirection_uri={REDIRECTION_URI}&state={SOME_STATE_HASH}&presel={SOME_AGENCY}&agency={SOME_AGENCY}&agencytype=forsk,folk&force_login=0,1&idp={SOME_IDP}

Authorization response

see https://tools.ietf.org/html/rfc6749#section-4.1.2

If login goes well, a redirect will be returned to the defined {REDIRECT_URI} with the following parameters:

  • code: The authorization code generated by login.bib.dk. The authorization code expires after 5 minutes, and is a one time token.
  • state: If the "state" parameter was present in the client authorization request, the exact value is returned to the client.

{REDIRECTION_URI}/?state={SOME_STATE_HASH}&code={AUTHORIZATION_CODE}

An authorization_code indicates that a user has logged in with the access platform. An authorization_code is a one-time code that can be used to retrieve an access token. This is done in cold 2.

1.1.2. Access Token Request.

request:

See https://tools.ietf.org/html/rfc6749#section-4.1.3

The client makes a request to the token endpoint by sending the, following parameters using the "application/x-www-form-urlencoded" format to https://login.bib.dk/oauth/token

  • grant_type: Value MUST be set to "authorization_code".
  • code: authorization code that was returned from previous call to oauth/authorize.
  • redirect_uri: Must be the same redirect_uri, which is used to retrieve authorization code.
  • client_id: client ID.
  • client_secret: client secret.

curl -X POST https://login.bib.dk/oauth/token -d 'grant_type=authorization_code&code={AUTH_CODE}&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&redirect_uri=REDIRECT_URI}'

response

See https://tools.ietf.org/html/rfc6749#section-4.1.4

{"access_token": "RsT5OjbzRn430zqMLgV3Ia", "expires_in": 3600

1.2. Password Grant

see https://tools.ietf.org/html/rfc6749#section-4.3

This type of authorization can be used for login in client applications that cannot make use of the authorization code grant method. This could be native applications. When using this type of authorization, single-signon will not possible.

1.2.1. Obtain credentials

It is up to the client application to obtain the user credentials. It is good practice for the client application to discard the user credentials when a valid token is obtained.

1.2.2. Access Token Request.

request:

See https://tools.ietf.org/html/rfc6749#section-4.3.2

The client makes a request to the token endpoint by sending the, following parameters using the "application/x-www-form-urlencoded" format to https://login.bib.dk/oauth/token

  • grant_type: Value MUST be set to password.
  • username: borchk user userId
  • password: borchk user password.
  • agency: Agency ID is the library the user needs to authenticate against.
  • client_id: client ID.
  • client_secret: client secret.

The client application needs to authenticate using client ID and client Secrect.

curl -X POST https://login.bib.dk/oauth/token -d 'grant_type=password&password={PASSWORD}&username={username}&agency=${AGENCY_ID}&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}'

response

See https://tools.ietf.org/html/rfc6749#section-4.3.3

{"access_token": "RsT5OjbzRn430zqMLgV3Ia", "expires_in": 3600

2. Get userinfo

2.1. User info request http://login.bib.dk/userinfo

The client makes a request to the token endpoint by sending the, following parameters using the "application/x-www-form-urlencoded" format to https://login.bib.dk/userinfo

  • access_code: access_token retrieved from through oauth/token.

curl https://login.bib.dk/userinfo -H 'Authorization: Bearer {ACCESS_TOKEN}'

if biblioteklogin is used as idp, the userinfo endpoint will use borchk, to get information about the status uf the user, from the library used. If this kind of information is not needed, it can be skipped, by appending ?skipBorchk=1 to /userinfo

response:

Returns a map of attributes. Which attributes that a returned depends on the client configuration. The default configuration returns uniqueId and municipality

{
  "attributes": {
    "userId": "0101701234",
    "uniqueId": "9ea16d6a9e2cbec5215fa4c35cfc3ea231a3481ffce5f75e998029527d3ec1e0",
    "agencies": [
      {
        "agencyId": "710100",
        "userId": "0101701234",
        "uidType": "CPR"
      },
      {
        "agencyId": "714700",
        "userId": "12345678",
        "uidType": "LOCAL"
      }
    ]
  }
}

possible user attributes

  • cpr: CPR-number E.g. 010203791234
  • libraries : List of libraries a user is registered on 
          {
        "agencyId": "710100",
        "userId": "0101701234",
        "uidType": "CPR"
      },
      {
        "agencyId": "714700",
        "userId": "12345678",
        "uidType": "LOCAL"
      }
    ]
  • municipality : Muncipality number (see http://www.linking.dk/lokalportaler/kommuner.html)
  • userId : 'User ID used at login, normally it corresponds with CPR, but this is not garantied'
  • uniqueId : Anonymous user ID

As default only municipality and uniqueId is returned. If any other attributes is required, it needs to be configurated in the client.

3. Log out

To log out of the access platform, redirect to: https://login.bib.dk/logout/?access_token={ACCESS_TOKEN}

This will also remove the single-signon cookie.

If authorization was done using a password grant, it is possible to revoke the access_token by making a DELETE request to the /oauth/revoke endpoint:

curl -X DELETE https://login.bib.dk/oauth/revoke?access_token={ACCESS_TOKEN}

4. Single Logout

For information about single logout flow see - single-logout

5. Introspection

Endpoint to return a token status and some other useful informations about a given token

The requesting client must be authorized to access the introspection endpoint. Authorization is set in the smaug client configuration.

{
  "introspection": true,
}

Example call:

curl --user CLIENT_ID:CLIENT_SECRET -X POST https://login.bib.dk/oauth/introspection?access_token=SOME_ACCESS_TOKEN

Returns:

{
    "active": true, // false if token is not recognized or expired
    "clientId": "id_of_the_client", 
    "uniqueId": "0101701234", // null if token is anonymous
    "type": "authorized", // authorized/anonymous according to token
    "expires": "3600",
    "agency": "some_agency",
    "name": "name_of_the_client",
    "search": {
      "profile": "client_search_profile",
      "agency": "some_agency"
    },
    "contact": {
        "owner": {
          "name": "owner_name",
          "email": "owner_email",
          "phone": "owner_phone"
        },
        "Technical contact": {
          "name": "technical_name",
          "email": "technical_email",
          "phone": "technical_phone"
        }
    }
}

Only {"active": false} response is returned if token is not recognized or expired.

Error messages

{"error": "Missing param access_token"}

  • access_token is missing or empty

{"error": "Invalid client and/or secret"}

  • Request from an unknown client - client can't be validated

{"error": "Client is not allowed to use /introspection endpoint"}

  • Client missing authorization to access the /introspection endpoint