This article highlights the details of Higher Logic’s support of OAuth 2.0 Authorization Code Single Sign-On flow. Higher Logic has requirements in order for this to be set up as the Single Sign-On solution for your Higher Logic Thrive Community (Thrive Community) site.
NOTE: The standards mentioned in this article are derived from the OAuth 2.0 Open ID Connect standard.
Authorization Request
This is the request made from the Thrive Community site to the Identity Provider for the authorization of the user attempting to login to Higher Logic. This is an HTTP GET request to the authorization endpoint which is provided by the client in the Technical Worksheet and in most cases, the URL follows the format below.
https://[client_login_site_domain_and_path]/authorize?client_id=[client id]&response_type=code&scope=[scope]&
redirect_uri=https://[HL_site_domain]/HigherLogic/Security/OAuth/Authentication.aspx&state=[generated state token]
The URL would also include query string parameters that would be the trust between Higher Logic and the Identity Provider. The query string parameters we are requiring to send with the request are below.
NOTE: All values below are URL encoded in the request.
| Parameter | Description |
|---|---|
| client_id | Unique identifier for the service provider. In this case for Higher Logic. |
| response_type | Describes the type of verification that will be passed back to the service provider after authentication on the identity provider’s end. In this case, the value will always be “code”. |
| scope | Defines the access privilege that is being requested. In most cases, “profile” should be the value here, however, the requirement is that the access privilege should include the user’s unique identifier that is used by Higher Logic as the legacy identifier from the integration with the client’s user database. |
| redirect_uri |
The URL where the response from the authorization endpoint will land. This is also unique to the service provider and, in Higher Logic’s case, will be a Thrive Community site URL. This URL will always be: https://[HL_site_domain]/HigherLogic/Security/OAuth/Authentication.aspx |
| state | An opaque value used to maintain the state between the request and the callback. Higher Logic will fill this with a randomly generated value and will expect the same value back in the “state” query string parameter of the response. |
This request should resolve to a login page if the user logging in does not already have an active session on the identity provider side.
After logging in successfully with their credentials, the user should be redirected back to Higher Logic to the URL of the “redirect_uri” along with other items in the URL that the Higher Logic side will process and continue with the login flow.
The items in the URL that are expected post-login are below.
| Parameter | Description |
|---|---|
| code | Value that is generated by the identity provider end that will be used by Higher Logic in the next request to retrieve the “access_token” from the identity provider’s “token” endpoint. |
| state | The same value passed in the request as stated in the previous table. Used for verification of the response. |
Example authorization request and response:
Request
GET /oauth2/v1/authorize?client_id=1234&response_type=code&scope=profile&redirect_uri=
https%3A%2F%2Fhigherlogic.connectedcommunity.org%2FHigherLogic%2FSecurity%2FOAuth%
2FAuthentication.aspx&state=56789
HTTP/1.1
Host: dev-468598.okta.com
Response after login on authorization endpoint
https://higherlogic.connectedcommunity.org/HigherLogic/Security/OAuth/Authentication.aspx
?code=1357&state=56789
Token Request
Once Higher Logic receives the items in the above table in the URL after the redirect from the authorization endpoint, the request to the token endpoint on the identity provider side is created.
This request is an HTTP POST request to the token endpoint URL and will contain items within the body and header of the request. An example URL of the token endpoint is below:
- https://[client_login_site_domain_and_path]/token
The item in the Header that Higher Logic will send to the token endpoint is below:
| Header Key | Description |
|---|---|
| Authorization |
“Basic” authorization token that is the Base-64 encoded client ID and client secret value. It is in the format: |
The items in the Body that Higher Logic will include in the request are below:
NOTE: All values below are URL encoded in the request.
| Body Parameter | Description |
|---|---|
| grant_type | Describes the type of verification that will be used against the identity provider token endpoint. This will always be “authorization_code“ in Higher Logic’s request. |
| code | The same value returned from the response of the authorization request as described earlier in the article. |
| redirect_uri | The same value specified in the authorization request as described earlier in the article. |
A successful response from the token endpoint will contain in the body an “access_token” value which will be sent in the next request to the “userinfo” endpoint on the identity provider side. The response’s format is expected to be a JSON object with a field exactly named “access_token“. An example is below.
{
…
“access_token”:”[token value]”,
…
}
Example Token request and response:
Request
POST /oauth2/v1/token? HTTP/1.1
Host: dev-468598.okta.com
Authorization: Basic MTIzNDU6MTIzNDU2Nw==
Content-Type: application/x-www-form-urlencoded
code=1357&grant_type=authorization_code&redirect_uri=
https%3A%2F%2Fhigherlogic.connectedcommunity.org
%2FHigherLogic%2FSecurity%2FOAuth%2FAuthentication.aspx
Response
{
"access_token": "11bbe063-8b09-498a-a18d-e0237fe801db",
}
UserInfo Request
This request is for the information that Higher Logic requires that describes the logging in user, particularly the unique identifier of the user that is utilized as the Member Key of the user on the Higher Logic platform obtained through the integration with the client’s user database.
This request is an HTTP GET request with only items in the Header. An example URL of the userinfo endpoint is below.
- https://[client_login_site_domain_and_path]/userinfo
The item in the Header is described below.
| Header Key | Description |
|---|---|
| Authorization |
“Bearer” authorization token that is the “access_token” received from the response from the token endpoint as described previously in the document. It is in the format: “Bearer " + access_token" |
The response from this endpoint is also expected to be a JSON Object with the unique ID of the user as a field within the object. An example is below.
{
…
“[unique id field]”:”[unique id]”,
…
}
Once the above proper response is received from the endpoint and the unique id is obtained by the Higher Logic side, the login flow will be complete and the user will be logged into the identity provider side as well as Higher Logic and the user will be redirected to the original starting page on the Higher Logic side that they started the login process on.
Example UserInfo request and response:
Request
GET /oauth2/v1/userinfo? HTTP/1.1
Host: dev-468598.okta.com
Authorization: Bearer 11bbe063-8b09-498a-a18d-e0237fe801d
Response
{
"_Member_Number": "155488498541651",
"FirstName": "Jane",
"LastName": "Doe",
"Email": "Jane.Doe@email.org"
}
For the above, “_Member_Number” is what is required to complete the login to Higher Logic.