Authentication to Giosg
There are two supported authentication flows, as described by OpenID Connect specification:
- Implicit Flow (a.k.a Implicit Grant) used by e.g. front-end-focused web apps
- Authorization Code Flow (a.k.a Authorization Code Grant) used by e.g. server-based web apps (NOT YET IMPLEMENTED!!!)
To add Giosg authentication to your app, you first need to create a Giosg account, if you don’t already have one, and then 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 you Giosg App. These are addresses in your app for receiving authentication responses from Giosg, as discussed later. (NOT YET IMPLEMENTED!!!)
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.
|ID token||Includes identification information of the authenticated user, as a JSON Web Token. This is meant for the application for receiving basic information about the user (and verifying its validity). E.g. to show some basic information about them in the UI.|
|Access token||Used to authorize requests to Giosg HTTP API and Real-time API as the authenticated user. The application does not need to parse its contents.|
|Refresh token||Used in the Authorization Code Flow to get a new access token when the old one expires.|
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:
||string||Which URL issued the token (
||string||The ID of the user, as an UUID (e.g.
||array of strings||An array with exactly one string that matches the provided
||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.|
||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.|
||string||The ID of the user’s organization, as an UUID (e.g.
If the ID token was requested with an
profile scope, the following claims will be included as well:
||string||The full name of the user|
||string||The first name of the user|
||string||The last name of the user|
||string||Full URL to the user’s avatar, if any|
If the ID token was requested with an
|string||The email of the user|
||boolean||Whether or not the email address has been verified|
Example authorization header
Authorization: Bearer 1234567890abcdefghijklmnopqrstuvwxyz
With HTTP API requests, you include the token to the
Authorization header of every request:
Authorization: Bearer <access_token>
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.
The refresh token will only be available in the Authorization Code Flow which is NOT YET IMPLEMENTED!
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”).
The authentication process should go like this:
- The user opens the web app in the browser (e.g.
- 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.
- The UI shows the “Sign in” link or button
- User clicks the “Sign in” button
- User’s browser is redirected to the authentication URL (
https://service.giosg.com/identity/authorize?…) with an authentication request.
- User submits their username and password, if they are not already signed in to Giosg
- User’s browser is redirected back to the service’s redirect URI with an authentication response.
- The web app checks if the URI hash indicates an error, and that the
statematches the one sent in the authentication request
- The web app parses the
id_tokenfrom the URI hash and persists them to local/session storage
- 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
- The web app includes
Authorization: Bearer <access_token>header to every AJAX request made to Giosg HTTP APIs.
- 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:
- Redirect the user to authentication endpoint like in step 5, optionally prompting the user first
- Attempt to perform a “silent refresh”
Authentication request with Implicit Flow
Example authentication request with redirect URI
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:
The endpoint requires several parameters, which must be encoded with URI Query String Serialization.
The following parameters exist:
||required||A list of “scope” strings separated by single whitespace characters. At least one of them must be
||required||With Implicit Flow this needs to be
||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.|
||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
||required||The value that will be included unmodified as the
||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).|
||optional||If you provide value
Authentication response with Implicit Flow
Example of a successful authentication response URI
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 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:
||This value is always
||The access token that the app can use with APIs. Its lifetime is specified by
||The ID token as a JSON Web Token that the app can decode and get verified user information.|
||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.|
||The base URL for a WebSocket connection that client can use to subsribe real-time changes. See below for usage instructions!|
Example WebSocket URL after appending the access token
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 depending on whether or not the URL already contains character
If the authentication is not successful, then the response contains the following parameters:
||The error code as a string. See the table below for the possible values and their meaning.|
||Human-readable text description of the error, encoded in ASCII|
||The value of the
error code can be one of the following:
||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.|
||Client authentication failed (e.g., unknown Giosg App, or unrecognized Giosg’s internal client).|
||The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.|
||User’s interaction of some form to proceed and the
||User needs to authenticate but the
Silent access token refresh with Implicit Flow
When the access token expires, you need to retrieve a new one in order to continue using APIs. Unlike Authorization code flow 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:
- The web app creates an invisible iframe that navigates to the authentication request URL with an additional parameter
- The identity service re-authenticates the user if possible without showing an user interface
- The identity service redirects the iframe to a
redirect_uripage hosted by the web app
- The page in the iframe sends the result (new access token or error) to the parent page
- The main web app page receives the result from the iframe and stores the new token
- The iframe is removed from the element
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.
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:
The parameters are:
||required||To which frame the results will be sent. Either
||required||The origin of your web app, used as the
||required||The ID of your Giosg App as registered to Giosg. Matches the
When the page is loaded, it will send the following message to the parent frame or the opener page:
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:
- Determine your web app’s origin, including protocol, host name and any port number, e.g.
- Build your Authentication Callback URI as described above (remember URI encoding), e.g.
- Register this URI as one of the allowed redirect URIs for your web app
- When building re-authentication request URI, use this as an
redirect_uriparameter (remember URI encoding again) for the authentication request URI, e.g.
- Register an
messageevent handler for your web app’s Window object
- Create an hidden iframe and use this URI as the
srcattribute for it
- Wait for the iframe to send a message to your web app (starting with
- Strip the
giosg-auth-callback:prefix from the message and parse the authentication response from the rest of the string
- If the response contains an error, show a message to the user prompting them to re-authenticate themselves