About

info-beamer supports OAuth2 authorization. This allows easy integration of third-party apps and fully uses the existing permission system. Apps can request access to data for an info-beamer account. Once access is granted an app can control some aspects of an info-beamer account on behalf of a user. They can implement features not currently provided by info-beamer itself.

Data access is fine-grained. An app should request just the permissions required to fullfill its task. The info-beamer user granting access is in complete control and can review requested permission prior to granting them to a third-party app.

Granted permissions are handled as account access (similar to granting access to an account to other info-beamer users) and are shown on the account permission page. Users can revoke, review or even customize the granted permissions.

OAuth2 support

info-beamer implements the OAuth2 authentication token and code flow. It's highly recommended that you use the code flow if possible. info-beamer doesn't use client secrets. Instead it implements the PKCE extension for a secure code/access token exchange.

Assuming the code flow, the general idea is as follows:

1. A user visits a third-party page implementing an info-beamer app.
2. The user clicks on a Authorize access button on that page.
3. They are redirected to info-beamer.com
4. info-beamer.com will show then a consent page. This page shows the permissions requested by the app and allows the info-beamer user to choose whether to grant or reject access to their account. This step is skipped if the user previously granted access.
5. If the user grants access, they are redirected back to the app page. A authorization code is included in the redirect Url.
6. The app page issues an HTTP request to info-beamer.com and exchanges the authorization code with an access token.
7. The app uses that access token to issue API request to the info-beamer API on behalf of the info-beamer user.

Creating a new app

You can manage your OAuth apps in your permission management screen. Note that you currently cannot yet make your app publicly available. Get in contact with support for that. While your app might not be publicly available yet you can still test everything by authorizing your own account.

Add authentication to a custom app

You'll need the client ID and must have configured a valid redirect uri back to your app. If a user of your app is ready to allow access to their account, your app can initiate the authentication flow required to retrieve an access token.

Requesting authorization

The first steps is to request authorization from the info-beamer.com user by redirecting to the info-beamer.com authorization endpoint.

GET https://info-beamer.com/oauth/authorize

The following request parameters are required:

The user is now either using an existing login session for their info-beamer account or can log in to their account. They will then be presented with a consent page describing the requested access given by the values provided in the scope parameter. Alternatively if the user previously granted access to the app, the consent screen is skipped and access is granted automatically.

Alternatively and app might redirect to the authorization endpoint and include additional scope values not requested in earlier authorization requests. This might happen if your app requires additional permission. In that case the user is shown the consent screen again and can choose if they want to grant or reject any additional permissions requested.

If they grant access, info-beamer redirects back the the Url provided in redirect_uri with the following query parameters added:

In case of an error or if the user or the info-beamer system denies the request, the following paramters are returned instead:

Retrieving the access token

The code returned to your app by info-beamer in case of a successful authorization isn't useful on its own. It cannot be used to issue API calls. You'll have to exchange it for an access token within 15 seconds first. This works as follows:

POST https://info-beamer.com/oauth/token

You'll have to include the following POST parameters when issuing this request:

You'll get a JSON response with the following values:

Refresh tokens

If your initial authorization code exchange returns a refresh_token value, you can exchange that for another access token later. Use the same token exchange API endpoint for that as follows:

POST https://info-beamer.com/oauth/token

You'll have to include the following POST parameters when issuing this request:

You'll get a JSON response with the following values:

Scopes

One major feature of OAuth2 is that an app can request only the permissions required to do its job. As a user of an app, it's not required to give an app full access to your account. An app the helps manage a user's devices should not have access their assets for example.

An app developer can specify the required permissions as "scopes". The info-beamer permission system already uses policies and scopes are mapped to policies. If you open up the policy list you'll see that some policies have an oauth scope. An app can request each of them by including the scope in its authorization request. The value of scope in the initial authorization redirect might look like this:

asset:read setup:full

If the user grants access to their account, the returned access token would be granted the two policies specified by asset:read and setup:full. You can check each policy to see what access they allow. In the example the returned access token would allow the app to query asset information and create, modify or delete setups.

An example authorization flow

Here's a full example of what a flow might look like. Once the user click on a button labeled (for example) "Access your info-beamer account", the app redirects to the following Url (Line breaks for illustration purposes only):

https://info-beamer.com/oauth/authorize
    ?response_type=code
    &client_id=4e2b0589b577dcf817c3714c4217c174
    &state=204789b5d63624681d2777356374f8c9cd3426413e4c4b121136d129
    &scope=device%3Aread%20check
    &redirect_uri=https%3A%2F%2Flexample.net%2F
    &code_challenge=sIPbr43EmYOnu7aCb1rJH_KWtX0ifHw59aJf985ZBR0
    &code_challenge_method=S256

The state value is randomly chosen by the app and must be unique for each authorization flow. You'll see further down how the code_challenge value was generated.

The user is now present a screen where they can chose to allow or deny this authorization request. The two requested permissions are given in the value of scope and in this example are device:read as well as check:

If the user grants access, they are directed back to the Url given in redirect_uri with two parameters added. This request looks like this:

https://example.net/
    ?code=00b4f5c25b827c56f81fe7cb03ad7058
    &state=204789b5d63624681d2777356374f8c9cd3426413e4c4b121136d129

The app must now check if the value of state matches the one it included in the initial redirect. If they don't match, the authorization must be aborted as that means that someone else (probably an attacker) started the authorization flow.

If the state matches, the app can now send a POST request to exchange the code for an access token. This request must send the following values as POST parameters (Line breaks in the POST body are again for illustration purposes only):

POST /oauth/token HTTP/1.1
Host: info-beamer.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=00b4f5c25b827c56f81fe7cb03ad7058&
client_id=4e2b0589b577dcf817c3714c4217c174&
redirect_uri=https://example.net/&
code_verifier=0156b7f6e38568f0f09ca94cbdc809c41a6ec87bacaf9279dc834621

The code is the one provided in the redirect back to the app. The redirect_uri must match the value used in the initial authorization flow redirect. Finally the code_verifier is the proof that your app initially started the authorization flow.

The code_verifier is a value your app randomly generated when initially redirecting to the authorization page. Remember the code_challenge included in the initial request? Its value is derived from the code_verifier. So instead of including the code_verifier in the initial request you include a derived value that only your app knows later. This prevents the "Authorization Code Interception Attack" problem. The derivation works by generating the SHA256 value of the code_verifier and encoding it with url safe base64 and removing any trailing = padding characters:

# Example Python code:
import hashlib, base64
print(base64.urlsafe_b64encode(hashlib.sha256(
    b'0156b7f6e38568f0f09ca94cbdc809c41a6ec87bacaf9279dc834621'
).digest()).rstrip(b'='))

# will output sIPbr43EmYOnu7aCb1rJH_KWtX0ifHw59aJf985ZBR0

The /oauth/token POST request then returns the following JSON value:

{
  "access_token": "SESSION-a0410213573bc3bb5223d39ec4712d2c",
  "expires_in": 604800,
  "scope": "check device:read",
  "token_type": "bearer"
}

Your app can now use the access_token to send API requests to the info-beamer API. You also know that this access token will expire in 604800 seconds. The returned scope values shows you which permissions the user granted to your app. If the value is "custom", the user modified the app access with their own custom access.