defaultheader

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 registeration.




Server-side Flow

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 requrest 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

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 authroization 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

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

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

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 neccessary information to construct Brightidea API request.

Parameters

Parameters Detail
client_id
required
This identifies your application. It is obtained when registering your app.
Sample value: "3b7a9896d23e467f9fc8d26320fb30cb"
client_secret
required
This authenticates your application
Sample value: "1c551eb2aece47a5b3a2c3a301c262d3"
code
required
This is the authorization code that is returned in the query string of the redirect_uri
Sample value: "dd2f47aa12e7502307016e3ff37a18a9062ad0db"
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"
grant_type
required
This is the type of request being made. In this case it is authorization_code
Sample value: "authorization_code"

Errors

  • unsupported_grant_type : Grant type "{grant_type}" not supported
  • invalid_request : The request method must be POST when requesting an Access Token
  • invalid_request : The grant type was not specified in the request
  • invalid_request : Missing parameter: "code" is required
  • invalid_client : Client credentials were not found in the headers or body
  • invalid_client : The client credentials are invalid
  • invalid_grant : Authorization code doesn't exist or is invalid for the client
  • invalid_grant : The Authorization Code has expired
  • redirect_uri_mismatch : The redirect URI is missing or do not match

Example Request

  • Method: POST
  • URL: https://auth.brightidea.com/_oauth2/token
  • Form data:

    • grant_type=authorization_code
    • client_id=3b7a9896d23e467f9fc8d26320fb30cb
    • client_secret=1c551eb2aece47a5b3a2c3a301c262d3
    • code=dd2f47aa12e7502307016e3ff37a18a9062ad0db
    • redirect_uri=http%3A%2F%2Fexample.com%2Foauth
    {
        access_token: "d2d3201e537267c9feb3b58f9a1875c3588fcf6f"
        expires_in: 3600
        token_type: "bearer"
        scope: null
        refresh_token: "a664d106026aa3567f91037136c7e2675fc5d270"
        systems:
        {
            client_name: "Example"
            host_name: "example.brightidea.com"
        }
    }
    


Refresh Token

Access Tokens is one of the required components for Brightidea API requests. However, it expires after one hour of its issue. Your app can invoke the entire Server-side Flow flow again to get a new one. Or, for better user experience, request for a new one through the use of the Refresh Token.

The Refresh Token is obtained at the end of a successful API Access Resource Request. Simply make a server side request to the token URL, passing the Refresh Token, and your app should receive a new Access Token. This eliminates the need of user re-authentication, resulting to better user experience.

The Token URL is set at app registration. Visit Edit App page to see what the setting is.

Parameters

Parameters Detail
client_id
required
This identifies your application. It is obtained when registering your app.
Sample value: "3b7a9896d23e467f9fc8d26320fb30cb"
client_secret
required
This authenticates your application
Sample value: "1c551eb2aece47a5b3a2c3a301c262d3"
refresh_token
required
This is the refresh toekn that is returned in a token endpoint request
Sample value: "a664d106026aa3567f91037136c7e2675fc5d270"
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"
grant_type
required
This is the type of request being made. In this case it is refresh_token
Sample value: "refresh_token"

Errors

  • unsupported_grant_type : Grant type "{grant_type}" not supported
  • invalid_request : The request method must be POST when requesting an sccess token
  • invalid_request : The grant type was not specified in the request
  • invalid_request : Missing parameter: "refresh_token" is required
  • invalid_client : Client credentials were not found in the headers or body
  • invalid_client : The client credentials are invalid
  • invalid_grant : Authorization code doesn't exist or is invalid for the client
  • invalid_grant : The authorization code has expired
  • redirect_uri_mismatch : The redirect URI is missing or do not match

Example Request

  • Method: POST
  • URL: https://auth.brightidea.com/_oauth2/token
  • Form data:

    • grant_type=authorization_code
    • client_id=3b7a9896d23e467f9fc8d26320fb30cb
    • client_secret=1c551eb2aece47a5b3a2c3a301c262d3
    • code=dd2f47aa12e7502307016e3ff37a18a9062ad0db
    • redirect_uri=http%3A%2F%2Fexample.com%2Foauth
    {
        access_token: "e58fe78b26814600068b9b7ec495af8bf139d274"
        expires_in: 3600
        token_type: "bearer"
        scope: null
        refresh_token: "3d44b236121b8095b75ea5fbcd9d954b9c78dd8d"
        systems:
        {
            client_name: "Example"
            host_name: "example.brightidea.com"
        }
    }
    





Client-side Flow

Known as the "Implicit Grant" in the OAuth2 spec, the Client-side Flow is mainly used for mobile or desktop applications. For more info on the this spec, visit: http://tools.ietf.org/html/rfc6749#section-4.2

Below are the steps on how user, your app and Brightidea interact in the client-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 API resources. See API resources 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 resources needed to access API.

client-side flow


API resources Request

To obtain an resources needed for API requests, all it takes is a redirect request. This corresponds to Step 2 of the Client-side Flow. Resources return 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.

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 token
Sample value: "token"
redirect_uri
required
This is the URL of the page that the browser will be redirected to with the access token. 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 access token. 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=token&redirect_uri=http%3A%2F%2Fexample.com%2Foauth


Brightidea Authentication Page

In response to the API resources 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 Client-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 Access Token in the query string with the parameter name: access_token, and a few other useful parameters. Redirect example:

http://example.com/oauth#access_token=1faa7784f2d75094d2ad649924261b25ba3ebc40&expires_in=3600&token_type=bearer&host_name=example.brightidea.com

Redirect URI is set when you register your app. Visit Edit App page to see what the setting is.

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





Password Credentials Flow

If you are buliding features such as data dump for reporting, or bulk upload ideas, where the process requires server-to-server interactions, the Password Credential flow can be used. This is known as the "Resource Owner Password Credentials Grant" in the OAuth2 spec. For more info, visit: http://tools.ietf.org/html/rfc6749#section-4.3

Keep in mind, with this flow, your process must already possesses the credential needed for authentication. And it should know the host name of a Brightidea system for API access. If not, you will need to build your own methods to obtain those information.

Below are the steps on how your process and Brightidea interact in the client-side flow:kit

Step 1: Make server request to Brightidea for API resources. See API resources Request for detail on how to make this request.

Step 2: Brightidea responses with the resources needed to access API.

brightidea authorization


API resources Request

To obtain an resources needed for API requests, 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 Step 1 of the Password Credentials Flow. Resources return include:

  • Access Token: A token that identifies the authenticated user session.
  • Host Name: The domain name of the Brightidea systems credential owner have access to. The credential owner may have access to mutiple domains. Your process must know which one to make API request against.
  • 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.

Parameters

Parameters Detail
client_id
required
This identifies your application. It is obtained when registering your app.
Sample value: "3b7a9896d23e467f9fc8d26320fb30cb"
client_secret
required
This authenticates your application
Sample value: "1c551eb2aece47a5b3a2c3a301c262d3"
username
required
This is the email of the authenticating user account.
Sample value: "jdoe@exampl.com"
password
required
This is the password of the authenticating user account.
grant_type
required
This is the type of request being made. In this case it is password
Sample value: "password"

Errors

  • invalid_request : Missing parameters: "username" and "password" required
  • invalid_grant : Invalid username and password combination
  • invalid_grant : Unable to retrieve user information

Example Request

  • Method: POST
  • URL: https://auth.brightidea.com/_oauth2/token
  • Form data:

    • grant_type=password
    • client_id=3b7a9896d23e467f9fc8d26320fb30cb
    • client_secret=1c551eb2aece47a5b3a2c3a301c262d3
    • username=jdoe%40example.com
    • password=x3Mtre07!
    {
        "access_token": "b60a40b34ea436e2523c3c959bd4a3fe9ac1a644",
        "expires_in": 3600,
        "token_type": "bearer",
        "scope": null,
        "refresh_token": "0aee58e29a59929a8ecf6498ca71337a219cfc63",
        "systems": [
            {
                "client_name": "Example System",
                "host_name": "example.brightidea.com"
            },
            {
                "client_name": "Test Affiliate",
                "host_name": "test.brightidea.com"
            }
        ]
    }
    


Refresh Token

With a valid Access Token, your process can make requests against Brightidea API. However, it expires after one hour of its issue. The Refresh Token, obtained from the API Access Resource Request, can be used to get a new Access Token.

Simply make a server side request to the token URL, passing the Refresh Token. This eliminates the need of re-authentication. The Token URL is set at app registration. Visit Edit App page to see what the setting is.

It is not recommended to store user credential locally for the purpose of re-authenticaion. It's a prefered practic to store Access and Refresh Token instead for token renewal.

Parameters

Parameters Detail
client_id
required
This identifies your application. It is obtained when registering your app.
Sample value: "3b7a9896d23e467f9fc8d26320fb30cb"
client_secret
required
This authenticates your application
Sample value: "1c551eb2aece47a5b3a2c3a301c262d3"
refresh_token
required
This is the refresh toekn that is returned in a token endpoint request
Sample value: "a664d106026aa3567f91037136c7e2675fc5d270"
grant_type
required
This is the type of request being made. In this case it is refresh_token
Sample value: "refresh_token"

Errors

  • unsupported_grant_type : Grant type "{grant_type}" not supported
  • invalid_request : The request method must be POST when requesting an sccess token
  • invalid_request : The grant type was not specified in the request
  • invalid_request : Missing parameter: "refresh_token" is required

Example Request

  • Method: POST
  • URL: https://auth.brightidea.com/_oauth2/token
  • Form data:

    • grant_type=authorization_code
    • client_id=3b7a9896d23e467f9fc8d26320fb30cb
    • client_secret=1c551eb2aece47a5b3a2c3a301c262d3
    • code=dd2f47aa12e7502307016e3ff37a18a9062ad0db
    • redirect_uri=http%3A%2F%2Fexample.com%2Foauth
    {
        access_token: "e58fe78b26814600068b9b7ec495af8bf139d274"
        expires_in: 3600
        token_type: "bearer"
        scope: null
        refresh_token: "3d44b236121b8095b75ea5fbcd9d954b9c78dd8d"
        systems:
            {
                "client_name": "Example System",
                "host_name": "example.brightidea.com"
            },
            {
                "client_name": "Test Affiliate",
                "host_name": "test.brightidea.com"
            }
    }
    




FAQ

Question: Can I use the Server-side flow on a client side app?

Answer: Yes you can. Just keep in mind if client_secret, used for API resources Request, is stored on the client side, it will no longer be a secret key.

Question: How do I refresh the Access Token once it expires using the Client-side flow?

Answer: Simply invoke the Client-side Flow flow again to get a new one Access Token.

Question: My app requires profile data of the logged in user. How do I get it?

Answer: After an access token is obtain make an API request to the GET member function to get member profile data.

Question: How do I use the access token to make an API request?

Answer: For API info, please visit API Section of the documentation.

Question: How can users of my app access a SSO enabled Brightidea system through "Brightidea Authentication"?

Answer: "Brightidea Authentication" is not currently supporting SSO.