NAV
curl

Introduction

What is BASE?

BASE, an authentication and authorization platform that allows organizations to quickly and easily create scalable single sign-on (SSO) for their business-to-business (B2B) web and mobile apps

Who is BASE designed for?

Modern enterprises are increasingly requiring their vendors to integrate with an existing sign sign-on identity provider. BASE targets companies that want enable SSO without having to dedicate engineering or infrastructure resources to building and maintaining an internal solution.

Why is this important?

Security is becoming a “must have” for customers and a differentiator between vendors. Building on Bitium’s extensive industry experience with security and single sign-on, BASE lets companies to quickly offer industry standard authentication methods in a scalable fashion.

Definitions

Item Definition Examples
Provider The SaaS service that is making use of BASE. Google
App A part of the SaaS service – there might be multiple apps involved in the delivery of the SaaS service. Google Drive, Salesforce, Trello
Customer The customer of the SaaS service provider. Acme Widgets,
User An end user associated with the Customer’s account. John Smith, Sue Robinson
Identity Provider The customer’s identity provider (IdP); this is where users are sent to authenticate themselves. AD FS, Bitium, Centrify, Okta, One Login, Ping
BASE The service provided by Bitium allowing Providers to easily implement SSO for their Customers.

Overview

From within the provider’s app, the customer (typically this is an admin role) can configure how their users authenticate into the app. Options include authentication protocol, username type and expected attributes. This information is sent to BASE through the API and BASE will respond with an authentication URL. When an anonymous user visits the app, they can be redirected to the authentication URL which will begin the SSO process.

Diagram of overall BASE flow

Setting Up Single Sign-On

Single sign-on is typically setup in an administration interface to the app. When using BASE, the setup is making a single call to the BASE API to pass the required parameters and to store the returned authentication URL. Apps will generally offer the admin the option to always enforce SSO or to make it optional. When SSO is always enforced, all users will be redirected to BASE for authentication. When SSO is optional, users are presented with a choice of either authenticating with username/password or through SSO.

Diagram of admin setup flow

Authenticating Users

Once the customer admin has setup SSO within the app, the end users can start to use SSO. When an anonymous user attempts to access a BASE-enabled app, they are redirected to BASE to begin the authentication process. BASE will then redirect to the user to their corporate identity provider (IdP). If the user is authenticated with their IdP, they will immediately be redirected to BASE, otherwise they will be prompted for their username and password before being sent back to BASE. After being returned to BASE, BASE will validate the IdP response, parse out the necessary values from the SSO response and POST a simple JWT payload to the app.

At this point, the app should validate the JWT token is authentic using a pre-shared secret and then establish a session for the user.

Diagram of user auth flow

Tutorial

One of the challenges with developing SSO solutions is that it requires both an identity provider and an app in order to simulate the entire flow.

To simplify the process for a developer, Bitium provides both a test identity provider and a webhook receiver. In this tutorial, we’ll show you how the authentication process works using these tools.

1. Define an App in BASE

First, from your BASE dashboard click the Add and Application button. You can define as many apps as necessary. A common pattern is to define an app for each environment: development, staging, production, etc…

Diagram of user auth flow

On the next screen you can define how the app behaves and what BASE should do after the user is authenticated by the IdP.

Diagram of user auth flow

First, give your app a name. Next you will select the format for the SAML name identifier. This value determines the format of the subject returned by the IdP - you can think of this like a username or user ID. Most likely you will want the default value of ‘emailAddress’

Lastly, BASE will need to know where to send the user’s information after authentication. Normally this would be a callback URL in your app, but for the purpose of this tutorial we will simulate the receiving application using Echo, Bitium’s webhook testing tool.

2. Setup a Webhook Receiver

Open up https://echo.bitium.com and click the “Create a New Echo” button. This will redirect you the results page for your new Echo.

Diagram of user auth flow

Echo will simply display any HTTP form data you send to it, which makes it a great way to inspect the result of BASE authentication. Copy the URL displayed in Echo. Make sure to leave the tab open as you’ll want it in order to inspect the results later.

Diagram of user auth flow

Now that we have a place the send the data, we can complete the Add an Application form in BASE. Paste the URL from Echo into the “Callback URL” box and click “Save and Continue.” Don’t worry about the attribute list - we can safely use the defaults for now.

3. Finish App Setup

Diagram of user auth flow

Now let’s test out our new app! Click the “Customers” link in the navbar…

4. Define a Customer

Diagram of user auth flow

Then click “Add a Customer”. On the next screen you’ll be able to fill in details about your customer.

Diagram of user auth flow

To complete the New Customer form, we will need some more information: * External ID – this is how you uniquely refer to the customer account in your system. BASE will pass this value back to you after a successful authentication. * Login URL – we’ll need to know where to send the user to start the authentication process. * x509 Certificate – BASE will use this certificate to sign the requests sent to the IdP.

Diagram of user auth flow

5. Setup a Test IdP

Fortunately, in addition to Echo, Bitium also provides a test IdP so you can easily simulate the flow your customers would go through. Go to https://idp.bitium.com and setup a test IdP.

Diagram of user auth flow

On the next screen, you can copy “Sign In URL” and “X509 Certificate” values and paste those into the BASE new customer form.

Diagram of user auth flow

Finally, the finish setting up the new customer, select if you want BASE to digitally sign the SAML request (usually yes) and select the app you setup previously.

Diagram of user auth flow

6. Test Authentication

Now we’ve completed setting up a test IdP and a test App. Now lets see if it will all work.

First, click on the Authentication URL from your newly created customer. This will open a new window and start the SAML authentication flow.

Diagram of user auth flow

On the following screens, you will see the test IdP login flow. Our test IdP does not try to validate credentials, so you can enter whatever values you wish in order to generate a SAML response.

Diagram of user auth flow Diagram of user auth flow Diagram of user auth flow

After the final screen, the SAML response will get sent to BASE. Once BASE has parsed and validated the SAML payload it will extract the required values and send them to the defined callback URL – in this case, the Echo you setup previously.

7. Review the Output

Now go back to the Echo you setup in step 2 and refresh the screen. You’ll see the result of the authentication flow expressed as a JavaScript Web Token (JWT). For a comparison, review the contents of the JWT against the original SAML response – you can find the SAML responses in BASE under the “Auth Logs” menu.

Diagram of user auth flow

BASE API

API Authentication

Calls to the BASE API from the App require an API token. You can generate or revoke tokens from the API Token menu item on the BASE dashboard.

The API token can be used with an Authorization header to make authenticated calls the BASE API:

curl -H "Authorization: token [api token]" https://[account-id].base.bitium.com/api/v1/events.json

Create A New Customer and Identity Provider (SAML)

curl -X POST -H "Authorization: token [api token]" https://[account-id].base.bitium.com/api/v1/launchers.json \
  --data "external_id=1234" \
  --data "user_info={\"name\":\"John Public\"}" \
  --data "customer_name=Acme+Corp" \
  --data "provider_name=AD+FS" \
  --data "login_url=http://example.com/saml/login" \
  --data "application_id=my-application" \
  --data "x509_certificate=%0A-----BEGIN+CERTIFICATE-----%0AMIIC%2FzCCAeegAwIBAgIQG2mrBAP063Tvx3VYoLAXZzANBgkqhkiG9w0BAQsFADAV%0AMRMwEQYDVQQKEwpiaXRpdW0taWRwMB4XDTE2MTExNTAxNTMwNloXDTI2MTExMzAx%0ANTMwNlowFTETMBEGA1UEChMKYml0aXVtLWlkcDCCASIwDQYJKoZIhvcNAQEBBQAD%0AggEPADCCAQoCggEBAKxRaHWCnBv5LGzSke4E636PWKARjiO%2B7YLfCar4Cgxmb8jY%0A%2BKA%2FMzx41M2P%2F5NovpFPfAodcHC%2FOJj9UTyvcfr5mAvZytmMC0iahMiglm5y1FlG%0Ao4v0UYegJfUzAp1v3HqtUghd8iqzT2Bs9sGrsr2yNoN9x%2B1jWAtKQFacDBrsROPG%0ATpIVwmO9TLVagy6eMuNU6VnIBKbkkS7UYGaG%2BtIEaaVDwBp8CGliM57AqvDdM%2B8H%0AyQUq4saAvl1ijk5VYEnPsTUn7VoNog4PjMq%2F2qA7Vr%2BNT43aHZtrlX9TRFuLfddx%0AEeU7HnpsIQqEruPwW3%2B14qufuhjHq%2Fy4ukfotb0CAwEAAaNLMEkwDgYDVR0PAQH%2F%0ABAQDAgWgMBMGA1UdJQQMMAoGCCsGAQUFBwMBMAwGA1UdEwEB%2FwQCMAAwFAYDVR0R%0ABA0wC4IJbG9jYWxob3N0MA0GCSqGSIb3DQEBCwUAA4IBAQB%2F2TFjSvEfl4LtOKr0%0Ak2knMpP%2F5Ub2To0YuV01I9m6NESFTZtg3fgbks9OlFdBJDrivU0kPFhmQngyUnp8%0AmGcTycM2WaKZ84YnuqlXlN4MwO2cweY5yZdEri%2FbJTQTq2ZOtP%2BGbksZllvoyzdg%0Akqho36tKh%2BNfjCw%2B1qWqz4sYIzjuB5K%2FNG90wF3xE0SAvBUBvldcjz%2F40z15twc%2F%0AfKcgP%2FbwaBxplZ4j9HVyN6c0SkGi3x3JoMm5fi1RVhryJhPcMDeUC1jt01OpB6Zx%0AhPPhnMMujcWR0XlUaVRmYAHq2f9MjtOY7yx3xnaNqhhkAGyhGYYqTKjvZ81SrdUE%0A4qpr%0A-----END+CERTIFICATE-----%0A"

The above command returns JSON structured like this:

{  
   "id":"989d401b-d974-44b7-bfac-09298e131698",
   "provider_id":"9468a288-a7c3-4bfb-a671-bd4c7472c3ec",
   "application_id":"f5d0dc70-d447-4e04-98ae-f42cb60cce39",
   "redirect_uri":"https://[account-id].base.bitium.com/a/989d401b-d974-44b7-bfac-09298e131698"
}

HTTP Request

POST https://[account-id].base.bitium.com/api/v1/launchers.json

Parameters

Parameter Required Type Description
external_id Yes String Identifier to be sent back as part of audience attribute in the JWT token. To be used to scope user to a specific accounts in your app.
user_info Yes JSON Object A JSON object with desired user info, used to annotate customer event logs. At a minimum, requires a key name. Example: {"name":"John Q. Public"}
customer_name Yes String The display name the app uses for the customer. This is shown in the authentication logs
provider_name Yes String A name for the customers’ IdP
login_url Yes URL The location where the user is redirected to authenticate. Must be reachable by the end user but not necessarily by either BASE or the app (i.e behind customer’s firewall)
logout_url No URL The location where the user is sent for single-log-off (SLO)
x509_certificate Yes String The X509 certificate used to sign the requests between BASE and the IdP. Typically this is provided by the customer’s IdP.
application_id Yes String Application identifier – this is pre-defined during the initial setup of the app in BASE

JWT Structure

After a user is successfully authenticated via BASE, a JWT payload will be sent to the callback URL.

The structure of the JWT looks like this:

[
  {
    "firstName":"John",
    "lastName":"Doe",
    "email":"john.doe@example.com",
    "iss":"my-application",
    "aud":"an-id-your-app-will-understand",
    "sub":"anything you want here",
    "iat":1479166131,
    "nbf":1479165831,
    "exp":1479166431
  },
  {
    "typ":"JWT",
    "alg":"HS256"
  }
]

JWT layout

In addition to any attributes defined on the app in the BASE console, the following elements are also passed through in the JWT

Attribute Type Description
iss string (Issuer) the application_id you setup in the BASE console
aud string (Audience) The external_id you defined when you setup the customer in BASE. Typically this is used to identity the customer account in multi-tenant applications.
sub string (Subject) The username passed from the customer’s IdP
iat timestamp (Issued At) when the JWT was issued
nbf timestamp (Not Before) time after which the JWT can be considered valid
exp timestamp (Expiry) time after which the JWT should be considered expired

Errors

The BASE API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request is malformed or missing a parameter
401 Unauthorized – Your API key is wrong
404 Not Found – The specified object could not be found
406 Not Acceptable – You requested a format that isn’t json
500 Internal Server Error – We had a problem with our server. Try again later.