Skip to content

OAuth2 Authentication

Overview

This tutorial describes how to use OAuth2 authentication and how to add it to your Giosg App.

Prerequisites

Before you can use and setup OAuth2 authentication, you should of course have your Giosg account and an Giosg App.

OAuth2 overview

Giosg uses an OpenID Connect compatible authentication flow based on OAuth2.

There are two supported authentication flows, as described by OpenID Connect specification:

Giosg also supports single sign-on authentication flow:

  • SSO Authentication Flow used by Giosg apps to provide authentication to Giosg system without user sending credentials.

Getting started

To add Giosg authentication to your Giosg App, you first need to register a new Giosg App. Your app ID will be the client ID discussed in this documentation.

You also need to add at least one "redirect URI" to your Giosg app. These are addresses in your app for receiving authentication responses from Giosg, as discussed later.

OAuth2 tokens

There are multiple types of tokens used for authentication and authorization of a user, as specified by OpenID Connect and OAuth2. Here's a short summary of all of them.

Token Description
ID token Includes identification information of the authenticated user, as a JSON Web Token. This is meant for the app for receiving basic information about the user (and verifying its validity). E.g. to show some basic information about user in the UI like name.
Access token Used to authorize requests to Giosg HTTP API and Real-time API as the authenticated user. It's format depends on what authentication flow was used to request it.

ID token

The ID token is encoded as JSON Web Token (JWT). Your web app can decode this token and extract the included data object. The object will contain attributes called "claims". These claims contain useful information about the user who is being authenticated, such as the name and email address.

The following claims are available:

Claim Type Description
iss string Which URL issued the token (https://service.giosg.com/identity/authorize)
sub string The ID of the user, as an UUID (e.g. 7ce5ccdb-aa0f-470d-ad49-240448aba6a0)
aud array of strings An array with exactly one string that matches the provided client_id, i.e the ID of the Giosg App
exp integer Expiration time on or after which the ID Token is no longer valid. Its value is a number of seconds from 1970-01-01T00:00:00Z as measured in UTC.
iat integer Time at which the token was issued. Its value is a number of seconds from 1970-01-01T00:00:00Z as measured in UTC.
nonce string The nonce parameter from the authentication request unmodified. Your web app should check that this matches the one you provided, to mitigate replay attacks.
org string The ID of the user's organization, as an UUID (e.g. 8f20a18f-7fb2-474a-aca0-ff4dd608ffc3)

If the ID token was requested with an profile scope, the following claims will be included as well:

Claim Type Description
name string The full name of the user
given_name string The first name of the user
family_name string The last name of the user
picture string Full URL to the user's avatar, if any

If the ID token was requested with an email scope, the following claims will be included as well:

Claim Type Description
email string The email of the user
email_verified boolean Whether or not the email address has been verified

Access token

Example usage in Authorization header

1
Authorization: Bearer 1234567890abcdefghijklmnopqrstuvwxyz

The access token is used with Giosg HTTP API requests and Real-time API WebSocket connections.

With rest API requests, you include the token to the Authorization header of every request. If received with Implicit flow, it is used with a Bearer word in the Authorization header.

Authorization: Bearer <access_token>

If received with an Authorization Code Grant Flow, it is used with a Token word:

Authorization: Token <access_token>

Authorization Code Grant Flow returned token is same as User API Token but automatically generated for the user.

Always use the word from the token_type attribute before the access token in the Authorization header!

For more information, see the Authorization with an access token.

For information how to use the access token with WebSocket connections, see Connecting to WebSocket.

Implicit Flow

Implicit authentication is suitable for front-end web applications that use the APIs directly from the browser (or, in technical terms, in the "User Agent").

Giosg authentication Implicit Flow

The authentication process should go like this:

  1. The user opens the web app in the browser (e.g. https://example.com/)
  2. The web app checks if the user is already authenticated by checking if there is an existing access token stored in the local/session storage. If already authenticated, the authentication flow can be skipped.
  3. The UI shows the "Sign in" link or button
  4. User clicks the "Sign in" button
  5. User's browser is redirected to the authentication URL (https://service.giosg.com/identity/authorize?…) with an authentication request.
  6. User submits their username and password, if they are not already signed in to Giosg
  7. User's browser is redirected back to the service's redirect URI with an authentication response.
  8. The web app checks if the URI hash indicates an error, and that the state matches the one sent in the authentication request
  9. The web app parses the access_token and the id_token from the URI hash and persists them to local/session storage
  10. The web app decodes the user's name from the ID token (which is JWT) and shows it in the UI, as well as the "Sign out" button
  11. The web app includes Authorization: Bearer <access_token> header to every AJAX request made to Giosg HTTP APIs.

  12. When the token(s) are about to expire, or when an API request is responded with 401 Unauthorized, the web app needs to refresh the token. With Implicit Flow, there are two options:

  13. Redirect the user to authentication endpoint like in step 5, optionally prompting the user first

  14. Attempt to perform a "silent refresh"

Authentication request with Implicit Flow

Example authentication request with redirect URI https://client.example.org/my_callback

1
https://service.giosg.com/identity/authorize?response_type=id_token%20token&scope=openid&client_id=5a8a201f-6999-462b-b4a2-bb08df897321&state=st4t3F0rCsRf&nonce=R4nd0MsTr1ng&redirect_uri=https%3A%2F%2Fclient.example.org%2Fmy_callback

An authentication request is an OAuth 2.0 Authorization Request done by the service to the Giosg's authorization server.

With Implicit Flow, the request is done with HTTP GET request to the following endpoint. In practice this is done by navigating the user's browser window to the request URL:

GET https://service.giosg.com/identity/authorize

The endpoint requires several parameters, which must be encoded with URI Query String Serialization.

The following parameters exist:

Parameter Required Description
scope required A list of "scope" strings separated by single whitespace characters. At least one of them must be openid. Other supported values are profile and email. The selected scopes affect the information included to the ID token. For example, to request user's basic info, you could use openid profile and to request email as well, you could use openid profile email. Remember to encode whitespaces, so an actual parameter would look like openid%20profile%20email.
response_type required With Implicit Flow this needs to be id_token token for receiving both ID and access tokens, or id_token for just the ID token. Note that in id_token token the words are separated by whitespace, and when included in the URI, the it must be encoded as id_token%20token
client_id required The ID of your Giosg App as registered to Giosg. Your app will act as a OAuth "client". The ID is in UUID format.
redirect_uri required Redirection URI to which the response will be sent. This must exactly match one of the URIs that you have allowed for your Giosg App! The https scheme is required!
nonce required The value that will be included unmodified as the nonce claim in the ID token. The value should be used to associate a client session with an ID Token, and to mitigate replay attacks.
state recommended Opaque value used to maintain state between the request and the callback. It will be sent back as-is in the authentication response. Recommended to prevent Cross-Site Request Forgery (CSRF, XSRF).
prompt optional If you provide value none then no authentication UI will be shown to the user. Instead an error authentication response is sent back if the user is not already logged in with valid session. Useful for "silent refresh". You can also use value login which will show the login UI even if the user already has a valid session.

Authentication response with Implicit Flow

Example of a successful authentication response URI

1
https://client.example.com/my_callback#token_type=bearer&id_token=12345abcdef&access_token=67890ghijklmn&expires_in=3600&state=st4t3F0rCsRf

When the user has completed the authentication process, the Giosg authentication service redirects the user to the provided redirect_uri. For example:

  • User has entered valid username and password. The browser is redirected back with a successful authentication response
  • User is already authenticated with a session in the Giosg authentication service. The browser is redirected back with a successful authentication response
  • The authentication request contains invalid parameters. The browser is redirected back with an error authentication response

The URI hash (after #) describes if the request was successful or not, and it will also contain the tokens for the application's use.

Response parameters are formatted in the same way than URI query parameters. All the values are encoded with URI Query String Serialization so you must decode them before use. Otherwise you might get invalid results.

For a successful authentication, the following parameters are included to the hash:

Parameter Description
token_type This value is always bearer
access_token The access token that the app can use with APIs. Its lifetime is specified by expires_in parameter. It is returned only if response_type request parameter was id_token token
id_token The ID token as a JSON Web Token that the app can decode and get verified user information.
state The request state parameter unmodified. Your app must verify that the value matches the one sent with the request in order to prevent CSRF attacks.
expires_in The number of seconds the access token is valid since the request was generated. After this the APIs won't accept the token and you need to retrieve a fresh token.
socket_url The base URL for a WebSocket connection that client can use to subsribe real-time changes. See below for usage instructions!
minimal_bar_version Internally used field. Don't use it.

Example WebSocket URL after appending the access token

1
wss://messagerouter.giosg.com/websocket?token=67890ghijklmn

In addition to traditional response parameters, successful responses contain a socket_url parameter. It describes the base URL that the client can use to connect with WebSocket for subscribing real-time changes. For example: wss://messagerouter.giosg.com/websocket. For more information see WebSocket API documentation.

Before connecting to WebSocket URL, the client MUST append the access_token as a token URL parameter. The client MUST ensure that the parameter is correctly appended even if the URL already contains parameters! In other words, you need to append either ?token=MY_ACCESS_TOKEN or &token=MY_ACCESS_TOKEN depending on whether or not the URL already contains character ?.

If the authentication is not successful, then the response contains the following parameters:

Parameter Description
error The error code as a string. See the table below for the possible values and their meaning.
error_description Human-readable text description of the error, encoded in ASCII
state The value of the state parameter included in the Authentication Request

The error code can be one of the following:

Error code Description
invalid_request The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.
invalid_client Client authentication failed (e.g., unknown Giosg App, or unrecognized Giosg's internal client).
invalid_scope The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.
interaction_required User's interaction of some form to proceed and the prompt parameter value in the Authentication request was none. The request cannot be completed without displaying a user interface for user's interaction.
login_required User needs to authenticate but the prompt parameter value in the Authentication request was none. The request cannot be completed without displaying a user interface for entering user's credentials.

Silent access token refresh with Implicit Flow

Silent token refresh

When the access token expires, you need to retrieve a new one in order to continue using APIs. Implicit Flow does not support refresh tokens. You need to refresh the token by performing another authentication request.

There are several methods how this re-authentication request could be done. An easiest solution is to automatically navigate user's browser to the identity service for re-authentication. However, this would have very distruptive impact on the user experience. Another method would be to perform the re-authentication in pop-up window, but in practice this has a limitation that it can only be done on user's interaction on the web page (e.g. click an element) in order to avoid pop-up blockers. This would also be distruptive for the user.

A better solution is to use a silent refresh by running the re-authentication in an invisible iframe element. It works like this:

  1. The web app creates an invisible iframe that navigates to the authentication request URL with an additional parameter prompt=none
  2. The identity service re-authenticates the user if possible without showing an user interface
  3. The identity service redirects the iframe to a redirect_uri page hosted by the web app
  4. The page in the iframe sends the result (new access token or error) to the parent page
  5. The main web app page receives the result from the iframe and stores the new token
  6. The iframe is removed from the element

The prompt=none parameter will tell the identity service to not show any user interface but instead redirect back with an error if the user cannot be re-authenticated without an UI. For example, the user's session has expired on the identity service, or the user is required to re-enter their password.

If the silent refresh fails due to not able to show an UI for the user, the web app could then display an message that the user needs to re-authenticate and provide a link which starts the re-authentication in a traditional way, in the browser window or in a pop-up.

The silent refresh method requires that the web app hosts a separate web page used as redirect_uri. The page is typically blank (as it won't be visible to the user) and contain a short script that delivers the re-authentication result to the parent frame (where the actual web app is running).

However, to make things easier, Giosg provides an useful Authentication Callback page that you can use instead of implementing your own redirect landing page.

Authentication Callback Page

The Authentication Callback Page is an helpful service that you may use instead of implementing your own redirect URI for your web app when performing an Implicit Flow authentication in an pop-up or in an iframe.

Warning

IMPORTANT! Consider your app's security!

By using Authentication Callback Page you will expose your user's tokens to the whole origin of your web app! Therefore you should only use this if you can trust all the code in the same origin. Never use this method if any untrusted code can run in the same host name than your web app! In those cases, you need to implement your authentication redirect pages yourself.

The Authentication Callback page will use JavaScript's cross-origin messaging (Window.postMessage()) to send the authentication result (the URI hash) to your web app, which your web app can then parse like with traditional authentication. For security, the message will always be sent to the specific origin that you must specify beforehand.

The Authentication Callback Page URI has the following format:

https://service.giosg.com/identity/callback?target=parent&origin=YOUR_ORIGIN&client_id=YOUR_CLIENT_ID

The parameters are:

Parameter Required Description
target required To which frame the results will be sent. Either parent when used in an iframe, or opener when used in a pop-up window.
origin required The origin of your web app, used as the targetOrigin parameter for the Window.postMessage call. The wildcard origin (*) is not allowed for security reasons.
client_id required The ID of your Giosg App as registered to Giosg. Matches the client_id parameter in the authentication request.

When the page is loaded, it will send the following message to the parent frame or the opener page:

giosg-auth-callback:#token_type=bearer&id_token=12345abcdef&access_token=67890ghijklmn&expires_in=3600&state=st4t3F0rCsRf

Your app should filter only messages that starts with giosg-auth-callback:. Everything after this should be considered equal to the URI hash sent with the authentication response.

Here's how you enable the Authentication Callback Page for your web app:

  1. Determine your web app's origin, including protocol, host name and any port number, e.g. https://client.example.com
  2. Build your Authentication Callback URI as described above (remember URI encoding), e.g. https://service.giosg.com/identity/callback?target=parent&origin=https%3A%2F%2Fclient.example.com&client_id=5a8a201f-6999-462b-b4a2-bb08df897321
  3. Register this URI as one of the allowed redirect URIs for your web app
  4. When building re-authentication request URI, use this as an redirect_uri parameter (remember URI encoding again) for the authentication request URI, e.g. https://service.giosg.com/identity/authorize?response_type=id_token%20token&scope=openid&client_id=5a8a201f-6999-462b-b4a2-bb08df897321&state=st4t3F0rCsRf&nonce=R4nd0MsTr1ng&redirect_uri=https%3A%2F%2Fservice.giosg.com%2Fidentity%2Fcallback%3Ftarget%3Dparent%26origin%3Dhttps%253A%252F%252Fclient.example.com%26client_id%3D5a8a201f-6999-462b-b4a2-bb08df897321
  5. Register an message event handler for your web app's Window object
  6. Create an hidden iframe and use this URI as the src attribute for it
  7. Wait for the iframe to send a message to your web app (starting with giosg-auth-callback:)
  8. Strip the giosg-auth-callback: prefix from the message and parse the authentication response from the rest of the string
  9. If the response contains an error, show a message to the user prompting them to re-authenticate themselves

Authorization Code Grant Flow

Authorization Code Grant Flow is used by apps and integrations running on the servers. It supports performing "offline" requests as a user (user is not logged in Giosg system). For example, your server might run some periodical task or react to some trigger from an integrated system, and you then want to perform actions in behalf of the user.

The downside with this approach is that you need a server-side application that communicates with the Giosg HTTP APIs securely, without exposing secrets or access tokens to the client side. The process also involves additional steps to ensure the security of the token. As an upside, the access token you receive does not expire (but may be revoked) so you can store it securely to your app's database without a need to refresh it.

Giosg authentication Authorization Code Grant Flow

The authentication process should go like this:

  1. The user opens the app in the browser (e.g. https://example.com/)
  2. The app checks if it has a valid session for an authenticated user. This has be done by the app provider by using some session authentication. If they are already logged in, it can skip the authentication flow.
  3. The UI shows the "Sign in" link or button
  4. User clicks the "Sign in" button
  5. User's browser is redirected to the authentication URL (https://service.giosg.com/identity/authorize?…) with an authentication request.
  6. User submits their username and password, if they are not already signed in to Giosg
  7. User's browser is redirected back to the service's redirect URI with an authentication response.
  8. The app checks if the URI query indicates an error, and that the state matches the one sent in the authentication request
  9. The app server parses the code from the URI
  10. The app server exchanges the code to the actual access token by making a server-side access token request to https://service.giosg.com/identity/token?… using its app ID and app secret
  11. The app server receives an access_token (and possibly the id_token) for the user and persists it securely to its database.
  12. When the app wants to retrieve information or perform actions in behalf of the user, it makes server-side request to the Giosg HTTP API including Authorization: Token <access_token> header

Warning

The app secret and the access token (received in this flow) must NEVER be exposed to the client-side code (e.g. in the JavaScript running in the browser, or in the compiled mobile app). They may only be used and stored on the servers of your app!

Authentication request with Authorization Code Grant Flow

Example authentication request with redirect URI https://client.example.org/my_callback

1
https://service.giosg.com/identity/authorize?response_type=code&scope=openid&client_id=5a8a201f-6999-462b-b4a2-bb08df897321&state=st4t3F0rCsRf&nonce=R4nd0MsTr1ng&redirect_uri=https%3A%2F%2Fclient.example.org%2Fmy_callback

An authentication request is an OAuth 2.0 Authorization Request done by the service to the Giosg's authorization server.

With Authorization Code Grant Flow, the request is done with HTTP GET request to the following endpoint. In practice this is done by navigating the user's browser window to the request URL:

GET https://service.giosg.com/identity/authorize

The endpoint requires several parameters, which must be encoded with URI Query String Serialization.

The following parameters exist:

Parameter Required Description
scope required A list of "scope" strings separated by single whitespace characters. At least one of them must be openid. Other supported values are profile and email. The selected scopes affect the information included to the ID token. For example, to request user's basic info, you could use openid profile and to request email as well, you could use openid profile email. Remember to encode whitespaces, so an actual parameter would look like openid%20profile%20email.
response_type required With Authorization Code Grant this needs to be code.
client_id required The ID of your Giosg App as registered to Giosg. Your app will act as a OAuth "client". The ID is in UUID format.
redirect_uri required Redirection URI to which the response will be sent. This must exactly match one of the URIs that you have allowed for your Giosg App! The https scheme is required!
nonce required The value that will be included unmodified as the nonce claim in the ID token. The value should be used to associate a client session with an ID Token, and to mitigate replay attacks.
state recommended Opaque value used to maintain state between the request and the callback. It will be sent back as-is in the authentication response. Recommended to prevent Cross-Site Request Forgery (CSRF, XSRF).
prompt optional If you provide value none then no authentication UI will be shown to the user. Instead an error authentication response is sent back if the user is not already logged in with valid session. You can also use value login which will show the login UI even if the user already has a valid session.

Authentication response with Authorization Code Grant Flow

Example of a successful authentication response URI

1
https://client.example.com/my_callback?code=123456789abcdefghij&expires_in=3600&state=st4t3F0rCsRf

When the user has completed the authentication process, the Giosg authentication service redirects the user to the provided redirect_uri. For example:

  • User has entered valid user name and password. The browser is redirected back with a successful authentication response
  • User is already authenticated with a session in the Giosg authentication service. The browser is redirected back with a successful authentication response
  • The authentication request contains invalid parameters. The browser is redirected back with an error authentication response

The URI query (after ?) describes if the request was successful or not, and it will also contain the code that the app can exchange for the access token.

Response parameters are encoded with URI Query String Serialization so you must decode them before use. Otherwise you might get invalid results.

For a successful authentication, the following parameters are included as query parameters:

Parameter Description
code The authorization code that the app can exchange to the access token.
state The request state parameter unmodified. Your app must verify that the value matches the one sent with the request in order to prevent CSRF attacks.

Contents of code parameters are following:

Parameter Description
jti Unique identifier for the code.
iat When the token was issued.
exp Expiration time for the token, valid for a very short time.
aud List of target audiences for these specific URLs. It is not accepted by any other API nor message router. This is always [https://service.giosg.com/identity/token].
iss Issuer of the code. This is always https://service.giosg.com/identity/authorize.
user_id ID of the user for his code can be used to get access token for. It is for this user ONLY and therefore it does not have permissions for other users' users prefixed APIs.
organization_id ID of the user's organization.
app_id ID of the app. Only this app is allowed to exchange this code to an access token.

If the authentication is not successful, then the response contains the following parameters:

Parameter Description
error The error code as a string. See the table below for the possible values and their meaning.
error_description Human-readable text description of the error, encoded in ASCII
state The value of the state parameter included in the Authentication Request

The error code can be one of the following:

Error code Description
invalid_request The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.
invalid_client Client authentication failed (e.g., unknown Giosg App, or unrecognized Giosg's internal client).
invalid_scope The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.
interaction_required User's interaction with some form is required to proceed and the prompt parameter value in the Authentication request was none. The request cannot be completed without displaying a user interface for user's interaction. One of these forms might be e.g. expired password.
login_required User needs to authenticate but the prompt parameter value in the Authentication request was none. The request cannot be completed without displaying a user interface for entering user's credentials.

Token request with Authorization Code Grant Flow

Example Token request with for an app with ID 2ac428cd-7fe2-43a0-bd6f-bb747f138ef9&

1
2
3
4
5
6
7
8
POST /identity/token HTTP/1.1
Host: service.giosg.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
  code=i1WsRn1uB1d9s8Xs89jf2la9i9d8fj9838&
  client_id=2ac428cd-7fe2-43a0-bd6f-bb747f138ef9&
  client_secret=2348523ui4u2349823h42938h42384h

A Token request is an OAuth 2.0 Authorization Request done by the service to the Giosg's authorization server. It is used to exchange an Authorization Code to a persistent access token.

With Authorization Code Grant Flow, the request is done with HTTP POST request to the following endpoint:

POST https://service.giosg.com/identity/token

The endpoint requires several parameters in the payload (which must be encoded in application/x-www-form-urlencoded):

Parameter Required Description
grant_type required This must be exactly authorization_code
code required This is the Authorization Code that will be exchanged to an access token.
client_id required The ID of your Giosg App as registered to Giosg. Your app will act as a OAuth "client". The ID is in UUID format.
client_secret required The secret string generated to your app and only known by your app!

Token response with Authorization Code Grant Flow

Example of a successful Token response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcmdhbml6YXRpb25faWQiOiIzMjQ3NTVjNi0wMzY4LTExZTktYjBhMC0wMjQyYWMxNTAwMGEiLCJzY29wZXMiOltdLCJ2ZXJzaW9uIjoyLCJqdGkiOiIzMjc2OGNmNi0wMzY4LTExZTktYjBhMC0wMjQyYWMxNTAwMGEiLCJhdWQiOlsidGVzdG1lc3N1IiwidGVzdHNlcnZlciJdLCJleHAiOjE1NDUyNTEzNjYsInVzZXJfaWQiOiIzMjUzYjdiYy0wMzY4LTExZTktYjBhMC0wMjQyYWMxNTAwMGEiLCJpc3MiOiJodHRwOi8vdGVzdHNlcnZlci9pZGVudGl0eS9hdXRob3JpemUiLCJpYXQiOjE1NDUyMDgxNjYuOTYyMzQsImFwcF9pZCI6bnVsbH0.949TQOro7yxwwYN-S1AQ4_Jcm5vMM0O07pHyiWysE1U",
    "token_type": "Token",
    "user_id": "d0daa859-645a-4953-a089-1951c913ca30",
    "organization_id": "365a9781-de37-4872-95e9-088ecbbd1111",
    "app_id": "e287032d-4898-4e1d-8da8-f2e51cc0e023"
}

If the code is valid and the app's client credentials are valid, then the API endpoint returns a JSON-encoded object as a payload. For a successful exchange, the following attributes are present in the response payload:

Attribute Description
access_token The access token (an "API key") that can be used to authorize API requests.
token_type Tells which keyword you must use in the Authorization header of your following API requests as a prefix for the access token. Currently, this value is always Token.
user_id ID of the user to which the access token grants an access
organization_id ID of the organization in which context the access token allows API requests
app_id ID of your app, matching the client_id that was defined as a parameter

If the authentication is not successful, then the status code is 400, and the response contains the following attributes:

Attribute Description
error The error code as a string. See the table below for the possible values and their meaning.
error_description Human-readable text description of the error, encoded in ASCII

The error code can be one of the following:

Error code Description
invalid_request The request is missing a required parameter, includes an unsupported parameter value, repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.
invalid_client Client authentication failed (e.g., unknown Giosg App, or unrecognized Giosg's internal client, or non-matching app secret).

Single sign-on authentication

SSO Authentication flow

Giosg provides single sign-on (SSO) authentication for Giosg Apps. If your organization wants to be able to use your own identity provider and skip Giosg's login prompt and automatically login the user to Giosg Console, then our SSO is your solution. In order to use our SSO your organization must have an SSO enabled Giosg App installed and enabled. These kind of apps are currently only provided by Giosg and to be able to create your own SSO app you must contact support@giosg.com.

Token request with SSO

Example Token request for SSO app:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
POST /sso/token HTTP/1.1
Host: service.giosg.com
Content-Type: application/x-www-form-urlencoded

email=bill@giosg.com&
  first_name=Bill&
  last_name=giosg&
  alias=Billie&
  permissions=settings%20users%20reports&
  organization_id=2ac428cd-7fe2-43a0-bd6f-bb747f138ef9&
  client_id=05af0a6b-b276-11e8-8f99-8c8590c2eeca&
  client_secret=2348523ui4u2349823h42938h42384h

A Token request is a request for SSO enabled apps to retrieve JWT token, which can be used as a valid login access token for the user with the given email. If there is no user in Giosg system with given email, a new user is created for the organization. This newly created user won't have password and can only login through the SSO. Note that on every token request the user's permissions, first_name, last_name, and alias will be updated. email nor organization_id won't update once the user has been created to Giosg on the first token request.

It is used to create/update user to Giosg system and to receive a non-persistent access token for the user.

With SSO, the token request is done with HTTP POST request to the following endpoint:

POST https://service.giosg.com/sso/token

The endpoint requires several parameters in the payload (which must be encoded in application/x-www-form-urlencoded):

Parameter Required Description
email required Email of the user which is going to be generated or retrieved.
organization_id required ID of the organization.
client_id required ID of the app.
client_secret required The secret string generated to your app and only known by your app!
first_name required First name of the user.
last_name required Last name of the user.
alias optional Alias which is used for the user in chat.
permissions optional List of permissions granted to the user.

Token response with SSO

Example of a successful Token response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
HTTP/1.1 201 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcmdhbml6YXRpb25faWQiOiIzMjQ3NTVjNi0wMzY4LTExZTktYjBhMC0wMjQyYWMxNTAwMGEiLCJzY29wZXMiOltdLCJ2ZXJzaW9uIjoyLCJqdGkiOiIzMjc2OGNmNi0wMzY4LTExZTktYjBhMC0wMjQyYWMxNTAwMGEiLCJhdWQiOlsidGVzdG1lc3N1IiwidGVzdHNlcnZlciJdLCJleHAiOjE1NDUyNTEzNjYsInVzZXJfaWQiOiIzMjUzYjdiYy0wMzY4LTExZTktYjBhMC0wMjQyYWMxNTAwMGEiLCJpc3MiOiJodHRwOi8vdGVzdHNlcnZlci9pZGVudGl0eS9hdXRob3JpemUiLCJpYXQiOjE1NDUyMDgxNjYuOTYyMzQsImFwcF9pZCI6bnVsbH0.949TQOro7yxwwYN-S1AQ4_Jcm5vMM0O07pHyiWysE1U",
    "token_type": "Login",
    "user_id": "d0daa859-645a-4953-a089-1951c913ca30",
    "organization_id": "365a9781-de37-4872-95e9-088ecbbd1111",
    "app_id": "e287032d-4898-4e1d-8da8-f2e51cc0e023"
}

If the required fields are valid and the app is installed for the organization, then the API endpoint returns a JSON-encoded object as a payload. For a successful exchange, the following attributes are present in the response payload:

Attribute Description
access_token The access token (an "API key") that can be used only to authorize a /sso/login request.
token_type Tells which kind of token this is. For this case it is Login.
user_id ID of the user to which the access token grants an access.
organization_id ID of the organization in which context the access token allows login request.
app_id ID of your app, matching the client_id that was defined as a parameter.

If the authentication was successful, the response status is 201 if a new user was created and 200 if existing user was updated. If the authentication is not successful, then the status code is 400, and the response contains the following attributes:

Attribute Description
error The error code as a string. See the table below for the possible values and their meaning.
error_description Human-readable text description of the error, encoded in ASCII.

The error code can be one of the following:

Error code Description
invalid_request The request is missing a required parameter, includes an unsupported parameter value, repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.
invalid_client Client authentication failed (e.g., unknown Giosg App, or unrecognized Giosg's internal client, or organization has not installed Giosg App, or Giosg App is disabled).

SSO Login with access token

Example SSO login request:

1
GET /sso/login?token=access_token HTTP/1.1

In order to log in user to Giosg Console without submitting credentials, you may use SSO Login. This has to be done from client-side since it will automatically redirect the user to Giosg Console. To do this, redirect your user to:

GET /sso/login?token=access_token

where the access_token should be token for the user. The token should be retrieved through SSO Token request. On successful login the user will be redirected to Giosg Console. On failed request the user will be redirected to Identity blocked view. Reasons why the login might fail are:

  • access_token is not actually valid (e.g. expired)
  • The Giosg App does not have is_sso_authentication_enabled as true
  • Organization does not have the Giosg App installed
  • The Giosg App is disabled and has to be re-enabled in order to get login work again