Authentication

UbSub uses OpenID Connect in order to authenticate applications that want to read and access the user's API. You can read more about OIDC on their website.

Authenticating with OIDC

Step 1: Obtain client credentials

First you need to get a client_id and secret. Currently, there is not an automated way to do this, so simply reach out to us if you have a plugin or application you'd like to connect to ubsub at support@ubsub.io

Step 2: Redirect user to authentication page

The first automated step is to send the user's browser to the OIDC permissions page to allow the user to grant the application permission to access user data. It requires the following parameters:

Parameter Comments
client_id Your client id obtained above
response_type This should always be code
scope A space-separated list of permissions you would like to be able to access
redirect_uri Where to redirect the user back to once they grant permission
state A unique string that can be used to identify the user when the redirect has happened

Here's an example URL to redirect to:

Url: https://app.ubsub.io/oidc

https://app.ubsub.io/oidc?
 client_id=<CLIENT_ID>&
 response_type=code&
 scope=<SCOPES>&
 redirect_uri=https://oauth2-login-demo.example.com/callback&
 state=834bef03-82f9-4fee-94d4-d7af5c5da8ca&

Scopes

Scopes should be separated by spaces. You need at least one scope to be able to do anything useful, eg user.

See Token Scopes for list of supported scope.

Step 3: Receive redirect

Once the user grants permission, they will be redirected back to the redirect_uri with the following parameters:

Parameter Comments
state The state provided in the original redirect above
code The code that was granted which can be turned in for an access_token in the next step

Upon receiving the redirect back, you should validate that the state returned matches the original state you sent. A simple way to do this is to store it in cookie before redirecting the user to ubsub, and validating it once the user gets back.

Step 4: Trade code for access_token

The access_token allows API calls to UbSub to access the user's information. You need to trade in the code from the previous step to get a token.

Make a call to the following API:

Url: POST https://app.ubsub.io/oidc/token

client_id=<CLIENT_ID>
&client_secret=<CLIENT_SECRET>
&grant_type=authorization_code
&code=<CODE>

Fill in the applicable fields above with your client credentials and code. grant_type must be authorization_code.

Response:

Upon success, you will receive the following:

{
  "access_token" : "super secret token",
  "id_token" : "user JWT token",
  "expires_in" : "Date that token will expire",
  "token_type" : "Bearer"
}

The token_type will always be Bearer. The access_token is secret and you should guard. The id_token will identify the user, and is talked about in the next step.

Step 5: Validate and parse id_token

id_token is a JWT (JSON Web Token). This JWT contains signed information about the user. There are many libraries to parse JWTs, and can be found on the linked website.

The JWT is signed with the client_secret.

It has the following well-defined fields:

{
  "iss" : "app.ubsub.io",
  "sub" : "<tokenUserId>",
  "aud" : "<your client id>"
}

The key that we'll need here is the sub field in order to identify the user and call the API.

Step 6: Call the API

Now that we have full permissions, let's call the API!

GET https://router.ubsub.io/api/v1/user/{sub}
Authorization: Bearer <access_token>

You should see information about the user!

Appendix

Google's OIDC Documentation is quite good and very closely matches UbSub's implementation.