Single Use Clients

For quick prototyping and simple client applications, the normal OAuth2 authorization code based flow may have too much overhead. It is still the preferred method of authorization, but we also provide a simplified alternative that may fit certain use cases better: Single use client applications.

What?

A single use client application is a client application that can be used to authorize and obtain an access token for, at most, one user. Once a user authorizes against a single user client, the client is consumed and cannot be used for further authorizations. Other than that, single use clients are just like normal client applications.

It attempts to solve the following:

• Dumb client. The client app can make web calls to the Blot're api and that's it.
• Decentralized and easy startup. The client can talk directly to Blot're to authorize.
• Decouple user from client. The OAuth2 implicit flow will not work because the client is dumb. Instead, the user has a smart device to perform the actual authorization flow.
• Low user overhead. The user's action should be no more difficult than the regular authorization flow.

Single Use Client Flow

The overview of the flow:

1. Client registers a new single use client application with Blot're and receives back client credentials and an access code. This code expires in 10 minutes.
2. Client saves creds and displays access code to the user.
3. User visits /v0/oauth2/redeem on any device and enters access code.
4. User is shown normal authorization page with client info.
5. If user accepts, they are shown success page. The access code is consumed and the single use client is bound to that user.
6. Now the client can exchange their creds plus access code for a token at the normal token endpoint /v0/oauth2/access_token

Creating a Single Use Client

The first step is to register a new single use client application. Your application should provide some basic client info to help the user understand who is requesting authorization and why.

From the client:

PUT https://blot.re/v0/oauth2/disposable
{
    "name": YOUR_CLIENT_NAME,
    "blurb": YOUR_CLIENT_BLURB
}

Blot're has no way of authorizing the validity of client apps so it is up to the user. You may want to include unique client identifying information in the blurb, such as serial number.

Information about the client is returned and should be stored by the client.

Example

PUT https://blot.re/v0/oauth2/disposable
{
    "name": "Toastmaster 5000",
    "blurb": "Realtime toast updates. SN: 32014668"
}

{
    "name": "Toastmaster 5000",
    "blurb": "Realtime toast updates. SN: 32014668",
    "id": "5550f0cb30047a1988017033",
    "secret": "MTc2OGE1OTgtMjZiNy00YWU2LWJkMDctMjhlNTEyNDMzNGM3",
    "code": "9IpfuRwV",
    "expires_in": 1200
}

User Authorization

As it stands, our new client application is unbound, meaning the any user can now authorize themselves against it. Our application should now display the access code 9IpfuRwV to the user and direct them to https://blot.re/v0/oauth2/redeem

On this page the user will be prompted to sign in and enter the 8 letter, case sensitive authorization code. If a user enters 9IpfuRwV, they will be taken to the authorization page for our new application.

If the user accepts, they are redirected to a success confirmation page. No response is sent anywhere. The user's role is now complete.

Obtaining an Access Token.

The client application can now exchange client credentials for an access token for the authorized user. This uses the standard access endpoint: https://blot.re/v0/oauth2/access_token

Required Parameters

• grant_type - Must be set to https://oauth2grant.blot.re/onetime_code
• client_id - Id of the single use client.
• client_secret - Secret of the single use client
• code - The access code returned for the single use client

Example

POST https://blot.re/v0/oauth2/access_token?grant_type=https://oauth2grant.blot.re/onetime_code&client_id=5550f0cb30047a1988017033&client_secret=MTc2OGE1OTgtMjZiNy00YWU2LWJkMDctMjhlNTEyNDMzNGM3&code=9IpfuRwV

{
    "access_token": "MmU2NjY5MjMtMjU5NS00OGI1LTk5ZjUtMzQ5ZWNhYmI0N2Y1",
    "token_type": "bearer",
    "expires_in": 259200,
    "user": {
        "id": "5550f2a63004a531be8820c5"
    }
}

You may only exchange credentials once. After, that the code is expired. You can however use a refresh token base flow.

There is no guarantee that the user of your application was the one who redeemed the code. If your application loses credentials or credentials expire, you must create a new disposable client and reauthorize against the user.