Create an admin site using Audiogum Abilities

You can let users sign into your website using their accounts. This document describes what you need to do to configure these capabilities.

Background

You should have a basic understanding of OAuth 2 with an authorization code. See the official OAuth page for more information.

It's also worth being familiar with the Audiogum Platform Documentation which describes all of the APIs that you'll use to enable sign in.

Overview

  1. You'll have to mark the users that you want to be able to sign in to your site. This is accomplished using 'Abilities'.
  2. You'll have to set up your website to redirect to Audiogum for sign in, and to receive a redirect back from Audiogum.

Step 1. only has to happen once for each user that you want to be able to sign in to your site.

Step 2. will happen every time they want to sign in.

1. Mark users

User accounts can have 'abilities'. An ability is a piece of configuration that is owned by an OEM administrator - which you will be as owner of the website.

You can add whatever relevent material you need to a user, and once they're signed in to Audiogum you'll be able to read the abilities from the user's configuration.

For example, you could use the following to indicate that a user cannot change anything from within the application.

{"roles":["reader"]}

Again: the content of the abilities section is entirely up to you - choose whatever data format will allow you to distinguish non-users and users, and if needed, the different capabilities that your users can have in your application.

The request to change the abilities of a user should be similar to the following:

POST https://api.audiogum.com/v1/users/<id>/abilities
Authorization: <basic auth based on your admin client_id and client_secret>
Accept: application/json
Content-Type: application/json

{"roles":["reader"]}

Where <id> is the ID of the user that you want to modify.

You can find <id> using GET /v1/user once the user has signed in.

2. Signing in

To sign a user in you'll have to perform the following steps:

  1. Construct an Audiogum sign in URL
  2. Direct the user to the sign in URL
  3. Handle a redirect back from Audiogum with a token
  4. Use the token to retrieve the user's abilities
  5. Check that the abilities allow the user to access your website.

2.1. Construct an Audiogum sign in URL

Create a login URL with the following form:

https://api.audiogum.com/v1/authorize?client_id=<client-id>&scope=read_userprofile&response_type=code

Replace <client-id> with your client ID.

2.2. Redirect the user to the sign in URL

When someone asks to sign in to your site, you'll have to redirect them to the URL that you created in stage 1. If your application is using Javascript it's common to use window.location.replace to change the URL of the browser. If you aren't using Javascript, the sign in link can point directly to Audiogum.

2.3. Handle a redirect back from Audiogum with a token

Once the user has signed in to Audiogum they'll be redirected back to your site, to the URL that was configured when you created your client account. The URL will contain a query parameter code which you should store.

2.4. Use the token to retrieve the user's abilities

Abilities are store in the user's configuration. To get the configuration make a call to the Audiogum user configuration endpoint.

Please see the Platform Documentation site for full details, but it should be enough to do the following

GET http://api.audiogum.com/v1/user/config
Authorization: Bearer <token>
Accept: application/json

Replace <token> with the token that you received in step 3. The response will be a JSON structure that might have a key abilities which will contain the structure that you added to the user in the first section of this document.

If the user doesn't have an abilities key then you haven't authorised the user to sign in to your site.

2.5. Check that the abilities allow the user to access your website.

Examine the contenets of the abilities structure, and use that to allow access to your website. For example, if you use roles for configuration, don't allow read-write access to a user with only a reader role.

Summary

+-------+          +---------+          +-----------+
| User  |          | Website |          | Audiogum  |
+-------+          +---------+          +-----------+
    |                   |                     |
    | Sign in           |                     |
    |------------------>|                     |
    |                   |                     |
    |      Redirect URI |                     |
    |<------------------|                     |
    |                   |                     |
    | Sign in           |                     |
    |---------------------------------------->|
    |                   |                     |
    |                   |        Redirect URI |
    |<----------------------------------------|
    |                   |                     |
    | Access token      |                     |
    |------------------>|                     |
    |                   |                     |
    |                   | Get abilities       |
    |                   |-------------------->|
    |                   |                     |
    |                   |           abilities |
    |                   |<--------------------|
    |                   |                     |