Authentication

Authentication is the act of providing credentials along with a request to Conductor. Conductor then determines whether the request is authorized. In general, requests made with invalid credentials are considered "unauthorized" by Conductor, and result in an HTTP response code of 401.

If Conductor determines a request has been made with valid credentials, but that the authorities associated with those credentials are inadequate for the request in question, then the request is considered forbidden and results in an HTTP response code of 403.

To make an authenticated request, a client must make a request to conductor and provide credentials and authorizing information with the request.

  • If Conductor determines the credentials are valid and the provided authorities are adequate, a 2xx response code is returned. The calling client may handle the response accordingly.
  • Else if Conductor determines the credentials are valid but authorities are inadequate, a 403 response code is returned.
  • Else Conductor determines the credentials are invalid and a 401 response code is returned.

The following sections describe the mechanisms supported by Conductor to provide authentication of requests.

BasicAuth

BasicAuth facilitates authorization of Conductor requests within the scope of a single Conductor API (Conductor uses many APIs). To implement BasicAuth, use the following steps:

  1. Populate the HTTP request header with:
Authorization: Basic <credentials>
  1. If validly authenticated, the HTTP response headers may contain a Set-Cookie with a JSESSIONID, which may then be used in lieu of the Authorization request header on subsequent requests during the lifetime of the session. Use of the JSESSIONID obviates the need for re-authentication during the lifetime of the session.

The value of <credentials> used in the HTTP request header is specific to a particular username-password pair. Calculate <credentials> using the following procedure:

  1. Concatenate a valid username-password pair with a colon separator.
  2. Obtain the ASCII bytes of the <username>:<password> concatentation.
  3. Apply Base64 encoding to the ASCII bytes.

For example, the BasicAuth <credentials> for the username-password pair <myname>:<mypass> becomes the following after encoding in Base64:

<myname>:<mypass> = bXluYW1lOm15cGFzcw==

OAuth2

OAuth2 facilitates authorization of Conductor requests within the scope of the entire suite of Conductor APIs. It therefore acts as a "single sign on" service for Conductor.

In general, OAuth2 consists of a client providing credentials to an Authorization Server. Upon validation of the credentials, the Authorization Server responds with a valid Access Token. Optionally, the response may include a Refresh Token, which may be used to obtain another Access Token once the previous one has expired. Once obtained, the client provides the Access Token with each request to a secured Resource Server. A Resource Server will authenticate a new request as long as the provided Access Token is valid and unexpired. Each member of the suite of Conductor APIs is a Resource Server within the context of OAuth2.

OAuth2 is implemented using the following procedure:

  1. Provide username-password and client credentials to the Conductor Authorization Server via a request of the following form:
POST: https://oauth2-conductor.link-labs.com/oauth/token
Content-Type: application/x-www-form-urlencoded
Request Body:
grant_type=password&username={user}&password={pass}&client_id={id}&client_secret={secret}
  1. A valid request yields a JSON response containing an Access Token and a Refresh Token:
Response Body:
{
  "access_token":"0bff3b89-1570-4470-a498-7b3cfbf0b971",
  "token_type":"bearer",
  "refresh_token":"f41fc298-c829-4a2a-998b-fa7e2fe30636",
  "expires_in":86399,
  "scope":"all"
}
  1. To authenticate requests to Conductor APIs (a Resource Server), provide a valid Access Token using a request header:
Authorization: Bearer <accessToken>

For example:

Authorization: Bearer 0bff3b89-1570-4470-a498-7b3cfbf0b971
  1. If a request fails and Conductor returns an Unauthorized 401 response, a new Access Token may be obtained by making a refresh request to the Conductor Authorization Server. The refresh request uses the Refresh Token provided in the initial response from the Authorization Server:
POST: https://oauth2-conductor.link-labs.com/oauth/token
Content-Type: application/x-www-form-urlencoded
Request Body:
grant_type=refresh_token&refresh_token={refresh_token}
&client_id={id}&client_secret={secret}

For example:

grant_type=refresh_token&refresh_token={f41fc298-c829-4a2a-998b-fa7e2fe30636}
&client_id={id}&client_secret={secret}
  1. A successful refresh request results in the same JSON response shown in Step 2, above.
  2. If it necessary to revoke an active Access Token prior to its expiration time (analogous to a "logout" operation of a session-based authentication scheme), a revocation request may be made using the Access Token to be revoked:
POST: https://oauth2-conductor.link-labs.com/oauth2/revoke
Authorization: Bearer <accessToken>

For example:

Authorization: Bearer 0bff3b89-1570-4470-a498-7b3cfbf0b971

0 Comments

Add your comment

E-Mail me when someone replies to this comment