Authentication

Before users can access Brightidea data through your app, they must first authenticate and authorize against Brightidea. Once completed, your app will have the permission and the resource to make API request for data on behalf of the users.

The easiest way to handle this is through the use of "Brightidea Authentication" page. The page takes user through the authentication and authorization steps, so you do not have to worry about building the mechanism for this process in your app. All it needs is the ability to interact with the page.

Your app must use OAuth 2.0 standard to interact with the "Brightidea Authentication" page. For information on the full OAuth 2.0 protocol, visit: http://tools.ietf.org/html/rfc6749. There are two methods of implementation: the Server-side flow and the Client-side flow. Each applies to different use cases, but both achieve the same end result:

Allow user to authenticate against Brightidea.
Allow user to authorize your app to access data.
Return an access token for data Brightidea API access.

All OAuth2 requests require HTTPS. Prior to implementation, make sure to register your app at app registration.

Server-side Flow {#server-side}

Known as the "Authorization Code Grant" in the OAuth2 spec, the Server-side Flow is mainly used for web applications. For more info on the this spec, visit: http://tools.ietf.org/html/rfc6749#section-4.1

Below are the steps on how user, your app and Brightidea interact in the server-side flow:

Step 1: User accesses your app.

Step 2: Your app redirects to "Brightidea Authentication" page. The purpose of this step is to request for Authorization Code. See Authorization Code Request for detail on how to make this request.

Step 3: User completes "Brightidea Authentication" page process. See Brightidea Authentication Page for detail.

Step 4: "Brightidea Authentication" page redirects back to your app with the Authorization Code.

Step 5: Your app will make a server side request to Brightidea. The purpose of this step is to request for API resources. See API Access Resource Request for detail on how to make this request.

Step 6: Brightidea response API resources. With this, your app can make API request for Brightidea data. See API for info on how to make API requests.

server-side flow

Authorization Code Request {#authorization_code}

Requesting for Authorization Code starts at Step 2 of the Server-side Flow. Obtaining a valid code is a requirement in the request for an Access Token at a later step. Below is resource info on how to make the request.

Parameters

Parameters | Detail ----------------------------------- | ----------------------------------- client_id
required |This identifies your application. It is obtained when registering your app
Sample value: "3b7a9896d23e467f9fc8d26320fb30cb" response_type
required |This specifies whether you need an authorization code or access token returned. In this case it is code
Sample value: "code" redirect_uri
required |This is the URL of the page that the browser will be redirected to with the Authorization Code. It should match the redirect uri specified when registering your app. It should be url encoded
Sample value: "http%3A%2F%2Fexample.com%2Foauth" state
optional |This value will be returned with the authorization code. It is most commonly used for CSRF mitigation
Sample value: "571d652fe7c119b"

Resource Information

HTTP Methods: GET

Request URL: https://auth.brightidea.com/_oauth2/authorize

Errors

redirect_uri_mismatch : The redirect URI provided is missing or does not match
invalid_request : Invalid or missing response type
invalid_client : The client id supplied is invalid
access_denied : The user denied access to your application

Example Request

Method: GET
URL: https://auth.brightidea.com/_oauth2/authorize?client_id={client_id}&response_type=code&redirect_uri=http%3A%2F%2Fexample.com%2Foauth

Sign in with Brightidea Button {#signwithbi}

You can certainly construct the request from scratch, or you can get some help from the code we provide below. Place this HTML on a page to show the "Sign in with Brightidea" button. Clicking on the button takes the user through the authentication and authorization process. The authorization code is returned to the app's redirect URI in query string.

Code: Copy and drop the the code into your app and replace value of client_id and redirect_uri.

<div id="login_button"><div id="login-brightidea"></div></div>

<script>
    var brightidea_conf = {
        element_id: 'login-brightidea',
        auth_domain: 'https://auth.brightidea.com',
        client_id: '3b7a9896d23e467f9fc8d26320fb30cb',
        redirect_uri: 'http://example.com/oauth'
    };

    var jq = document.createElement('script'); 
    jq.type = 'text/javascript'; 
    jq.src = 'https://images.brightidea.com/core/javascript/login.js';
    var sc = document.getElementsByTagName('script')[0];
    sc.parentNode.insertBefore(jq, sc);
</script>

Sign in button: at render, button displays on the page.

brightidea authorization

Brightidea Authentication Page {#loginwithbipageserver}

In response to the authorization code request, user is presented with the Brightidea Authentication page. To authenticate, user must put in his Brightidea credential. This corresponds to Step 3 of the Server-side Flow.

brightidea authorization

Once logged in the user is asked for authorization so your app can access the data on behalf of user.

brightidea authorization

At the end of the process, page redirects back to your app's Redirect URI with the authorization code in the query string with the parameter name: code. Redirect URI is set when you register your app. Visit Edit App page to see what the setting is. Redirect example:

http://example.com/oauth?code=dd2f47aa12e7502307016e3ff37a18a9062ad0db

At this point, your app completes Step 4 of the Server-side Flow.

API resources Request {#apiaccessresources_server}

With a valid authorization code, your app can request for the resources needed to make API requests. Those include:

Access Token: A token that identifies the authenticated user session.
Host Name: The domain name of the Brightidea system user authorized your app to access.
Expiration: The amount of time in seconds before the Access Token expires.
Refresh Token: Use for getting a new Access Token after expiration. See Refresh Token for more info.

All it takes is a server side request to the Token URL. The Token URL is set at app registration. Visit Edit App page to see what the setting is.

This corresponds to Step 5 of the Server-side Flow. Along with Access token, process returns all the necessary information to construct Brightidea API request.