OAuth Endpoints

1. Overview

In support of OAuth 2.0 IETF RFC 6749, the following endpoints are provided.

In support of OpenID Connect, the following endpoints are provided:

2. Authorize

This is an implementation of the Authorization endpoint as defined by the IETF RFC 6749 Section 3.1.

2.1. Request

Returns the OAuth login form for authorization

URI

GET /oauth2/authorize?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code

Table 1. Request Parameters

client_id [String] Required

The unique client identifier. The client Id is the Id of the Passport Application in which you you are attempting to authenticate.

redirect_uri [String] Required

The URI to redirect to upon a successful request. This URI must have been configured previously in the Passport Application OAuth configuration. See Applications in the Passport User Guide for additional information on configuring the redirect URI.

response_type [String] Required

The requested response type. This value must be set to code.

2.2. Response

Table 2. Response Codes
Code Description

200

The request was successful. The user is not logged in, the response will contain and HTML form to collect login credentials.

302

The requested user is already logged in, the request will redirect to the location specified in the redirect_uri on the request.

400

The request was invalid and/or malformed. The response will contain a JSON message with the specific errors. The error response JSON is covered in the OAuthError section of the API documentation.

500

There was a Passport internal error. A stack trace is provided and logged in the Passport log files.

2.3. Request

Authenticate the User

URI

POST /oauth2/authorize

Table 3. Request Parameters

client_id [String] Required

The unique client identifier. The client Id is the Id of the Passport Application in which you you are attempting to authenticate.

device [String] Optional Available Since 1.20.0

The optional unique device identifier for use with the offline_access scope. This is required if you’re using offline_access scope.

The offline_scope will be ignored if the device is not provided.

loginId [String] Required

The login identifier of the User. This might be their email or username.

password [String] Required

The User’s password.

redirect_uri [String] Required

The URI to redirect to upon a successful request. This URI must have been configured previously in the Passport Application OAuth configuration. See Applications in the Passport User Guide for additional information on configuring the redirect URI.

response_type [String] Required

The requested response type. This value must be set to code.

scope [String] Optional Available Since 1.19.0

The optional scope you are requesting during this grant.

Available grant types:

  • openid

  • offline_access Available Since 1.20.0

2.4. Response

Table 4. Response Codes
Code Description

200

The login form will be displayed, the user should expect some messaging indicating an error. One of the following conditions may be true:

  • Invalid login, the user does not exist, or the user has provided invalid credentials.

  • The current user action prevents this user from login.

  • Email has not been verified, the user is not allowed to login.

  • User is expired and login is prevented.

302

The user was successfully authenticated, the request will redirect to:

  • The location specified in the redirect_uri on the request.

    • The URL will contain the authorization code for use with the Token endpoint and state if provided.

  • Two factor authentication is enabled for this user, the redirect location will be to an HTML form allowing the user to input the two factor code.

    • Location: /oauth2/two-factor

  • The user’s password needs to be changed, the redirect location will be to an HTML form allowing the user to change their password.

    • Location: /password/change

400

The request was invalid and/or malformed. The response will contain a JSON message with the specific errors. The error response JSON is covered in the OAuthError section of the API documentation.

500

There was a Passport internal error. A stack trace is provided and logged in the Passport log files.

3. Logout

This endpoint provides a mechanism to invalidate the user’s session held by Passport, this effectively logs the user out of Passport.

3.1. GET Request

Log the User out

URI

GET /oauth2/logout?client_id={client_id}

Table 5. Request Parameters

client_id [String] Optional

The unique client identifier. The client Id is the Id of the Passport Application in which you you are requesting to logout, this value is used to identify the correct redirect URI. If the client_id is not provided the Logout URL defined in the Global OAuth Configuration will be used.

3.2. GET Response

Table 6. Response Codes
Code Description

302

The request was successful and the the redirect location will be determined by using the configuration values in the following precedence:

  • The logout URL defined in the Application OAuth configuration

  • The logout URL defined in the Passport System OAuth configuration

  • The root context / (slash)

400

The request was invalid and/or malformed. The response will contain a JSON message with the specific errors. The error response JSON is covered in the OAuthError section of the API documentation.

500

There was a Passport internal error. A stack trace is provided and logged in the Passport log files.

4. Token

This is an implementation of the Token endpoint as defined by the IETF RFC 6749 Section 3.2.

4.1. Request

Exchange the Authorization Code for a Token : Authorization Code Grant

URI

POST /oauth2/token

Table 7. Request Parameters

client_id [String] Required

The unique client identifier. The client Id is the Id of the Passport Application in which you you are attempting to authenticate.

code [String] Required

The authorization code returned on the /oauth2/authorize response.

grant_type [String] Required

The grant type to be used. This value must be set to authorization_code

redirect_uri [String] Required

The URI to redirect to upon a successful request. This URI must have been configured previously in the Passport Application OAuth configuration. See Applications in the Passport User Guide for additional information on configuring the redirect URI.

Example HTTP Request
POST /oauth2/token HTTP/1.1
Host: example-login.inversoft.io
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 436
client_id=3c219e58-ed0e-4b18-ad48-f4f92793ae32&code=+WYT3XemV4f81ghHi4V+RyNwvATDaD4FIj0BpfFC4Wzg&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fwww.vandelayindustries.com%2Flogin

Exchange User Credentials for a Token : Resource Owner Credentials Grant

Available Since Version 1.6.2

URI

POST /oauth2/token

Table 8. Request Parameters

client_id [String] Required

The unique client identifier. The client Id is the Id of the Passport Application in which you you are attempting to authenticate.

device [String] Optional Available Since 1.20.0

The optional unique device identifier for use with the offline_access scope. This is required if you’re using offline_access scope.

The offline_scope will be ignored if the device is not provided.

grant_type [String] Required

The grant type to be used. This value must be set to password

loginId [String] Required

The login identifier of the user. The login identifier can be either the email or the username.

password [String] Required

The user’s password.

scope [String] Optional Available Since 1.19.0

The optional scope you are requesting during this grant.

Available grant types:

  • openid

  • offline_access Available Since 1.20.0

Example HTTP Request
POST /oauth2/token HTTP/1.1
Host: example-login.inversoft.io
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 436
client_id=3c219e58-ed0e-4b18-ad48-f4f92793ae32&grant_type=password&loginId=bishop%40example.com&password=Setec+Astronomy

4.2. Response

Table 9. Response Codes
Code Description

200

The request was successful.

400

The request was invalid and/or malformed. The response will contain a JSON message with the specific errors. The error response JSON is covered in the OAuthError section of the API documentation.

500

There was a Passport internal error. A stack trace is provided and logged in the Passport log files.

Table 10. Response Body

access_token [String]

The OAuth access token as described by RFC 6749 Section 1.4

expires_in [Integer]

The time in seconds the token will expire from the time the response was generated.

id_token [String] Available Since 1.19.0

The OpenID ID Token. This token is represented as a JSON Web Token (JWT).

This field will be returned in the response when openid scope was requested.

refresh_token [String] Available Since 1.20.0

The refresh token as described by RFC 6749 Section 1.5

This field will be returned in the response when offline_access scope was requested.

token_type [String]

The token type as defined by RFC 6749 Section 7.1. This value will always be Bearer.

userId [String]

The unique Id of the user that has been authenticated. This user Id may be used to retrieve the entire user object using the /api/user API.

Example JSON Response
{
  "access_token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo",
  "expires_in" : 3600,
  "id_token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo",
  "refresh_token": "ze9fi6Y9sMSf3yWp3aaO2w7AMav2MFdiMIi2GObrAi-i3248oo0jTQ",
  "token_type" : "Bearer",
  "userId" : "3b6d2f70-4821-4694-ac89-60333c9c4165"
}

5. Introspect

This is an implementation of the Introspect endpoint as defined by the RFC 7662.

Available Since Version 1.18.0

5.1. Request

Inspect an access token issued by this OAuth provider

URI

POST /oauth2/introspect

Table 11. Request Parameters

client_id [String] Required

The unique client identifier. The client Id is the Id of the Passport Application for which this token was generated.

token [String] Required

The access token returned by this OAuth provider as the result of a successful authentication.

Example HTTP Request
POST /oauth2/introspect HTTP/1.1
Host: example-login.inversoft.io
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 436
client_id=3c219e58-ed0e-4b18-ad48-f4f92793ae32&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MTM3MTM3NzIsImlhdCI6MTUxMzcxMDE3MiwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiI3MWMxZjE5Yy1kZTRlLTRiZDEtODc3My0zNThkYmIwNWYxNWEiLCJlbWFpbCI6ImRhbmllbEBpbnZlcnNvZnQuY29tIiwiYXBwbGljYXRpb 25JZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMSIsImF1dGhlbnRpY2F0aW9uVHlwZSI6IlBBU1NXT1JEIiwicm9sZXMiOltdfQ.KxfM37hlw-5mKXOP9bCm7O6qdQdleT4gJmudhFueiJA

5.2. Response

Table 12. Response Codes
Code Description

200

The request was successful.

400

The request was invalid and/or malformed. The response will contain a JSON message with the specific errors. The error response JSON is covered in the OAuthError section of the API documentation.

401

The token provided in the request was not issued for the client_id provided on the request.

500

There was a Passport internal error. A stack trace is provided and logged in the Passport log files.

Table 13. Response Body

active [String]

When this value is true the token is valid and additional claims will be provided in the response body. When this value is false no claims will be provided in the response body.

applicationId [UUID]

The unique Id of the Application for which the User has been authenticated.

aud [String] Available Since 1.19.0

The client_id that was used to request the access token.

authenticationType [String]

The method used to authenticate the User which resulted in this JWT being generated. The possible values are:

  • APPLICATION_TOKEN - The User was authenticated using an Application Authentication Token.   Available Since 1.14.0

  • FEDERATED - The User was authenticated using a JWT from a federated Identity Provider.

  • JWT_SSO - A valid JWT authorized to one Application was exchanged for another JWT authorized to a different Application.

  • PASSWORD - The User was authenticated using a loginId and password combination.

  • REFRESH_TOKEN - The User requested a new JWT using a Refresh Token.

email [String]

The email address of the User.

email_verified [Boolean] Available Since 1.19.0

Indicates if the User’s email has been verified.

exp [Long]

The expiration instant of the access token expressed as UNIX time which is the number of seconds since Epoch.

iat [Long]

The instant that the access token was issued expressed as UNIX time which is the number of seconds since Epoch.

iss [String]

The issuer of the access token.

roles [Array<String>]

The roles assigned to the User in the authenticated Application.

sub [UUID]

The subject of the access token. This value is equal to the User’s unique Id in Passport.

Example JSON Response for a valid token
{
  "active": true,
  "applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
  "aud": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
  "authenticationType": "PASSWORD",
  "email": "test0@inversoft.com",
  "email_verified": true,
  "exp": 1487975407000,
  "iat": 1487971807000,
  "iss": "acme.com",
  "roles": [
    "admin"
  ],
  "sub": "858a4b01-62c8-4c2f-bfa7-6d018833bea7"
}
Example JSON Response for an invalid token
{
  "active": false
}

6. Userinfo

This is an implementation of the OpenId Connect Userinfo endpoint as defined by the OpenId Connect Section 5.3. This endpoint may be called using the GET or the POST HTTP method.

Available Since Version 1.19.0

6.1. Request

Returns the Claims about the authenticated End-User.

URI

GET /oauth2/userinfo

Returns the Claims about the authenticated End-User.

URI

POST /oauth2/userinfo

Table 14. Request Headers

Authorization [String] Required

The access token issued by Passport as a result of completing one of the supported authorization grants.

Example header: Authorization: Bearer <access_token>

6.2. Response

Table 15. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain a JSON message with the specific errors. The error response JSON is covered in the OAuthError section of the API documentation.

401

The Authorization header containing the access token is missing or malformed.

500

There was a Passport internal error. A stack trace is provided and logged in the Passport log files.

Table 16. Response Body

applicationId [UUID]

The unique Id of the Application for which the User has been authenticated.

aud [String]

The client_id that was used to request the access token.

authenticationType [String]

The method used to authenticate the User which resulted in this JWT being generated. The possible values are:

  • APPLICATION_TOKEN - The User was authenticated using an Application Authentication Token.   Available Since 1.14.0

  • FEDERATED - The User was authenticated using a JWT from a federated Identity Provider.

  • JWT_SSO - A valid JWT authorized to one Application was exchanged for another JWT authorized to a different Application.

  • PASSWORD - The User was authenticated using a loginId and password combination.

  • REFRESH_TOKEN - The User requested a new JWT using a Refresh Token.

email [String]

The email address of the User.

email_verified [Boolean]

Indicates if the User’s email has been verified.

exp [Long]

The expiration instant of the access token expressed as UNIX time which is the number of seconds since Epoch.

iat [Long]

The instant that the access token was issued expressed as UNIX time which is the number of seconds since Epoch.

iss [String]

The issuer of the access token.

roles [Array]

The roles assigned to the User in the authenticated Application.

sub [UUID]

The subject of the access token. This value is equal to the User’s unique Id in Passport.

Example JSON Response
{
  "applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
  "aud": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
  "authenticationType": "PASSWORD",
  "email": "test0@inversoft.com",
  "email_verified": true,
  "exp": 1487975407000,
  "iat": 1487971807000,
  "iss": "acme.com",
  "roles": [
    "admin"
  ],
  "sub": "858a4b01-62c8-4c2f-bfa7-6d018833bea7"
}

7. OpenID Configuration

The OpenID metadata describing the configuration as defined by Section 3. OpenID Provider Metadata.

Available Since Version 1.16.0

7.1. Request

Returns the well known OpenID Configuration JSON document

URI

GET /.well-known/openid-configuration

Example JSON Response
{
  "authorization_endpoint": "https://example-login.inversoft.io/oauth2/authorize",
  "claims_supported": [
    "iss",
    "sub",
    "aud",
    "iat",
    "exp",
    "nbf",
    "email",
    "email_verified"
  ],
  "grant_types_supported": [
    "authorization_code",
    "password",
    "refresh_token"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256",
    "RS384",
    "RS512",
    "HS256",
    "HS384",
    "HS512"
  ],
  "issuer": "example-login.inversoft.io",
  "response_types_supported": [
    "code"
  ],
  "scopes_supported": [
    "openid",
    "offline_access"
  ],
  "subject_types_supported": [
    "public"
  ],
  "token_endpoint": "https://example-login.inversoft.io/oauth2/token",
  "userinfo_endpoint": "https://example-login.inversoft.io/oauth2/userinfo",
  "userinfo_signing_alg_values_supported": [
    "RS256",
    "RS384",
    "RS512",
    "HS256",
    "HS384",
    "HS512"
  ]
}