Understanding Authentication

Applications connecting to the BlackBerry IoT Platform use the standard OAuth 2.0 protocol for authenticating and authorizing users and devices.

A successful OAuth 2.0 exchange results in receiving an access token, which is required for all BlackBerry IoT Platform API calls. The expiry time for an access token is six months. In addition, secure socket layer (SSL) is used for all communication between an application and the BlackBerry IoT Platform. For more information about the OAuth 2.0 protocol, refer to the OAuth 2.0 website.

The BlackBerry IoT Platform supports user-based and device-based authentication scenarios. Before we describe these scenarios in more detail, let's review a few concepts.

As mentioned earlier, there are basically two scenarios that BlackBerry IoT Platform supports for authentication. It's important that you understand them to best understand how to develop your applications and how to resolve any potential issues.

The user-based authentication scenario is exactly as the name implies. A user has to be available to enter their BlackBerry IoT Platform login credentials and authorize an application. This scenario to authenticate your application is useful when your users need to interact with the application. In addition, it's important to mention that on the user's device, there must be a web browser available for the user to consent the granting of permissions to the application. This scenario uses the Authorization Code flow as described in the OAuth 2.0 specifications. In comparison, device-based authentication doesn't require a user to be involved in the authentication process. Instead, the application uses information stored locally on the device to identify itself to the BlackBerry IoT Platform. This authentication scenario is useful when you're building applications that run on passive devices, such as vending machines, cars, etc. This scenario is similar Resource Owner Password Credentials Grant as described in the OAuth 2.0 specifications and transport layer security(TLS) is used in addition to SSL.

Overview of user-based authentication

In this scenario, the user must use a device that has a web browser on it. When the application first starts, it must authenticate the user's credentials. The application on the device redirects the user to a web browser, where users must enter their BlackBerry IoT Platform credentials.

Note: If it's the first time the user has logged in using the device, the BlackBerry IoT Platform handles the background activity of creating the device entity automatically.

After the user successfully signs in, an authorization code request is made that includes the API KEY and a callback URL. The user is redirected to an authorization page.

Authorize

From here, the user must authorize the application to access profile information from the BlackBerry IoT Platform. If the user clicks Allow access, then the page is redirected to the callback URL that was provided earlier. The callback URL contains the authorization code. However, if the user doesn't give consent, an error occurs.

After the application receives the authorization code, it sends the authorization code back to the BlackBerry IoT Platform to exchange it for an access token. As part of the exchange process, the BlackBerry IoT Platform sends an access token to the application.

From here, you're all good to start performing actions with the BlackBerry IoT Platform! The application can use the access token to make subsequent requests to the BlackBerry IoT Platform to get data and do other interesting things using the BlackBerry IoT Platform SDKs. If the access token expires, the application receives a 401 error (Unauthorized), and it must go through the process to request a new authorization code, accept the authorization code, and exchange the authorization code for a new access token. It isn't necessary for users to re-enter their login credentials.

Here's an illustration that describes the user-based authentication scenario.

Example

Details of user-based authentication

For user-based authentication, you must authenticate, authorize, and then obtain the access token to use the REST API. To handle authentication and authorization, applications must show the login page from the BlackBerry IoT Platform in a browser.

Authenticate the user

Applications must use the BlackBerry IoT Platform login webpage to authenticate the user's credentials.

Authorize the application

The https://bbryiot.com/auth/dialog/authorize endpoint allows the user to authorize the application. If the user hasn't logged in, the page redirects to the BlackBerry IoT Platform login page.

Here’s how you use the URL and the parameters to authorize an application:

https://bbryiot.com/auth/dialog/authorize?client_id=[SECRET KEY]&response_type=code
&redirect_uri=[redirect URI]&scope=[options to grant the application]
&state=[state value against CSRF]

The required parameters are client_id, response_type, and redirect_uri. The client_id specifies the API KEY of the application, the redirect_uri specifies the redirect URL to put the authorization code, and response_type must be code.

The scope parameter specifies the permissions that a user grants to the application. Ensure that each option you provide to the scope parameter is separated with a space (%20 when URL-encoded). In particular, you'll want to use this parameter to allow your application to inherit the capabilities of the logged in user.

You can use the state parameter to prevent cross-site request forgery on your application. It’s up to your client-side code to generate and validate the values to you pass as the state parameter to protect against cross-site request forgery (CSRF) attacks.

For detailed information about using the parameters, see the https://bbryiot.com/auth/dialog/authorize endpoint.

Here’s what the web page looks like if you provided the scope parameter with email and profile.

Example

On this page, users click one of these buttons:

Typically, for web applications, the callback URL is located on the same server as where the application resides. If you previously passed a value with the state parameter, you should verify that the returned value matches what's put at the callback URL. The callback URL would look something like the following if your callback was URL was myserver.com/callback:

 https://myserver.com/callback?code=[authorizationcode]&state=[state]

Obtain the access token

After you get an authorization code, your application must exchange the authorization code for an access token. Because the authorization code is valid for an extremely short period, it's recommended that you exchange your authorization code for an access token as soon as possible. To obtain the access token, your application must issue a POST request to the https://bbryiot.com/auth/token endpoint with the authorization code. The API KEY and API SECRET are passed in the HTTP Authorization Header. As part of the request, you must specify authorization code in the grant_type parameter.

For example, here’s how you call the https://bbryiot.com/auth/token endpoint:

curl https://bbryiot.com/auth/token -d grant_type=authorization_code -d code=[authorization code] -u [API KEY]:[API SECRET]

After a successful exchange, an access token is available in the access_token parameter of the response. Also included is other information you might find useful that include:

Here’s an example of what the response looks like:

{"access_token":"GUlIi_G0jKYdIfhtPc8AblYLaaebwKj0kdP29aNmlmYGUlIi_G0jKYdIfhtPc8AblYLaaebwKj0kdP29aNmlmY","device_id":"e1d28230-8b91-11e4-a752-27ab4c192d0e","grant_type":"authorization_code","scope":["email","profile"],"token_type":"Bearer"}

Use the API

Now that you have the access token, you can make calls to the REST API. The URL to use is https://bbryiot.com/api/1/[entity] where entity represents the API you're using. In fact, you can easily test the API calls using the REST API documentation.

Here's an example of how to use the access token in a GET request to get the name of the application using the Apps REST API using the API KEY:

curl -X GET https://bbryiot.com/api/1/apps/  -d "api_key"="[API KEY of the APP]" -H "Authorization:Bearer [access token]"

Here's an example of how to use the access token in a GET request to get the name of the application using the Apps REST API using the app_id, which is the universally unique identifier (UUID) of the resource:

curl -X GET https://bbryiot.com/api/1/apps/[app_id UUID] -H "Authorization:Bearer [access token]"

Overview of device-based authentication

In device-based authentication, no users are required to authenticate. This scenario is useful in manufacturing use cases where the device can be installed at the factory with the following:

Note: As part of your deployment flow, you must generate a private key and CSR. The CSR is used to generate a certificate on the BlackBerry IoT Platform. You download the certificate and put it on your device.

To install the information on a device, you put the API SECRET, API KEY, certificate, and private key on the device. For example, you could flash the information to a file on the device. For a manufacturing process that involves multiple devices (potentially thousands or millions), you could create a separate BlackBerry IoT Platform application to automate this process.

Example

The illustration above shows the steps in the process:

  1. Use the secp256r1 (prime256v1) elliptic curve to generate a CSR and private key.
  2. For the device you create on the BlackBerry IoT Platform, generate a digital certificate using the CSR from the previous step.
  3. Put the API SECRET, API KEY, generated key, and certificate onto the device.

Note: Certificates that are generated from the CSR are stored on the BlackBerry IoT Platform.

After a device has the information required and the application installed, it's ready to connect to the BlackBerry IoT Platform!

When the device is first turned on or when the application starts for the first time, it makes a token request to the BlackBerry IoT Platform. The API SECRET, API KEY, and certificate are used as part of the token request. A transport layer security (TLS) handshake is used to secure the communication and the device authenticates with the platform using the certificate. After successful certificate validation, the access token is returned to the device.

After the device receives the access token, then the device can perform operations on the BlackBerry IoT Platform. If the access token expires, the device receives a 401 (unauthorized) error. Then, a request for a new access token can be made using the certificate. If the certificate has been revoked or has expired, then a new certificate must be generated on the BlackBerry IoT Platform and put on the device.

Example

Details of device-based authentication

Device-based authentication uses an API KEY, API SECRET, and a X.509 certificate to obtain an access token. A private key is also required and is used as part of the transport layer security (TLS) handshake protocol with the BlackBerry IoT Platform during the token request. The private key isn't shared with anybody and is stored on the device.

Before you can get a certificate, you require a Certificate Signing Request (CSR). To generate a CSR, you require tools that support elliptical curve cryptography.

The CSR is required to generate new certificates on the BlackBerry IoT Platform, which you download and put on the device. You can also revoke the certificates that you don't want to be valid any longer using the BlackBerry IoT Platform.

After you get a certificate, you can use it as part of the token request to obtain an access token.

Use tools to generate CSR and key

The cryptography tool you choose must support key generation using secp256r1 (prime256v1) as the elliptical curve. Both the private key and Certificate Signing Request (CSR) must be PEM-encoded.

For example, you can use OpenSSL (open source) as your cryptography tool, however feel free to use any cryptography tools or libraries that support elliptical curve cryptography.

Here are the steps to illustrate how to generate a CSR and private key using OpenSSL (command-line):

Note: On Windows, ensure you configure the OPENSSL_CONF environment variable:

set OPENSSL_CONF=C:\OpenSSL-Win32\bin\openssl.cfg

  1. Generate an elliptical curve (EC) parameter for generating the key and CSR using secp256r1(prime256r1).
    openssl ecparam -name secp256r1 -out secp256r1_ecparam.pem
  2. Using the EC parameter, generate a CSR and private key using the command. As part of running this command, there are prompts for information that identify you and your company. Fill any or all fields, but leave the Common Name field blank because the device's UUID is put into that field. Any values you put in the Common Name fields are overwritten.
    openssl req -nodes -keyout private_key.key -newkey ec:secp256r1_ecparam.pem -new -out mycsr.csr
    Note: Don't put a password on the certificate.

A private key called private_key.key and a CSR file called mycsr.csr are created after you complete the above commands.

Generate a certificate

After you have a CSR, you use it to generate a certificate on the BlackBerry IoT Platform. You can upload the CSR to the adminstration console to generate certificate. For information about how to generate a certificate, see Generate certificates.

Obtain the access token

For a device to get an access token, your application makes a GET request to the https://auth.bbryiot.com/auth/token endpoint with the API KEY, API SECRET, and certificate. As part of the request, you specify password for the grant_type parameter. For example, here’s how you would use curl to call the https://bbryiot.com/auth/token endpoint:

curl https://auth.bbryiot.com/auth/token --key _myprivatekey.key_ --cert _mycertificate.pem_ -d grant_type=password -d username="" -d password="" -u _myApp_APIKEY_:_myApp_APISECRET_

After a successful call, an access token is part of the response. In the response, you also get the following information you may find useful to make REST API calls:

Here's an example of what the response with an access token looks like:

{"device_id":"b1d58230-8b91-22e4-a752-28ab4c192d0e","access_token":"qeHsPxIjHfXGGCgh/KfNr0Rtoc/Wzw90SEmeMWf1/xg7B9XzK3gb65Hhb\n45Lj9h3AC/XnWaobXvJBVfLKRq","token_type":"Bearer"}

Use the API

Now that you have the access token, you can make calls to the REST API. The URL to use is https://bbryiot.com/api/1/[entity], where entity represents the API you're using. In fact, you can easily test the API calls using the REST API documentation.

Here's how to use the access token in a GET request to get the name of an application:

curl -X GET https://bbryiot.com/api/1/apps/  -d "api_key"="[API KEY of the application]" -H "Authorization:Bearer [access token]"

Here's how to use the access token in a GET request to get the name of the application using the app_id, which is UUID of the entity:

curl -X GET https://bbryiot.com/api/1/apps/[app_id UUID] -H "Authorization:Bearer [access token]"

OAuth-2.0-endpoints

Depending on the OAuth 2.0 flow you use, these are the endpoints you can use:

https://bbryiot.com/auth/dialog/authorize

This endpoint is used for user-based authorization flows. This webpage lets a user authorize an application. It’s important to recognize that this endpoint redirects to a webpage and isn’t an API call. If the user hasn’t been authenticated, then the user is redirected to the BlackBerry IoT Platform login page. After the credentials (email and password) are authenticated, the user is redirected to the webpage to authorize the application.

Method:

N/A

Parameters:

Examples:

The following example shows how to call the endpoint to grant email and profile permissions, and specifies a callback URL of https://localhost/callback:

https://bbryiot.com/auth/dialog/authorize?response_type=code&redirect_uri=http%3A%2F%2Fmyserver%2Fcallback&scope=email%20profile%20inherit_user&client_id=myApp_APIKEY

https://bbryiot.com/auth/token

Use this endpoint for user-based authentication flows to exchange an authorization code for an access token. Calls to https://bbryiot.com/auth/token are authenticated using the API KEY and API SECRET, which are passed in the HTTP Authorization header.

Method:

POST

Parameters:

Examples:

In curl, here's how you would specify user-based authentication with the following information:

curl -k https://bbryiot.com/auth/token -d grant_type=authorization_code -d code=myAuthCode -u myApp_APIKEY:myApp_APISECRET

https://auth.bbryiot.com/auth/token

Use this endpoint for device-based authentication to get an access token. Calls to https://auth.bbryiot.com/auth/token are authenticated using:

A private key (not shared) is required as part of the Transport Layer Security (TLS) handshake protocol. Specifically, the key signs the handshake messages as part of the Certificate Verify message as described in RFC 4346.

Method:

POST

Parameters:

Example:

In curl, here's how you would specify device-based authentication with the following information:

curl -k https://auth.bbryiot.com/auth/token --key myprivatekey --cert mydeviceUUIDcert.pem -d grant_type=password -d username="" -d password="" -u myApp_APIKEY:myApp_APISECRET