Skip to content

OIDC SDK Integration#

This quickstart guide serves as an integration example for our trusted partners so that you will be able to evaluate, test, and launch LoginID’s authentication service for your own needs.

After going through this paper you should be able to have your application connect to our platform in just 4 simple steps that should take less than an hour.

Node.js Integration#

This section of the document assumes that you are using Node.js in your development environment. Additional independent configuration options and integration mechanisms will be described in the API Documentation that is still under development.

Step 1 - Define your Callback URL#

When the user authenticates themselves with LoginID (similar to authenticating with Google), LoginID will need to pass back control and information back to your servers. The Callback URL is the path that will be used to accomplish this and you will need to define it.

Callback URL https://exchange.domain/callback

Step 2 - Obtain your client keys#

In order to receive access to integrate LoginID you will need to create your client credentials. This is similar to the credentials you would create with Google to use Google authentication. This allows your servers to call LoginID services in a secure, authenticated fashion.

To obtain the client keys you will need to perform the following steps:

Create a new account#

new account

  • Navigate to https://sandbox.loginid.io/en/login and select the “Register a new account” option
  • Enter a username and hit the “Next” button
  • You will be prompted to authenticate using biometrics

Note

You must already have configured your own personal device for biometric authentication. The way that devices do this vary by browser, operating system and more.

Use your biometric capabilities#

bio

  • Your web browser will ask for permission to use your security key or other authenticator in order to proceed with account creation
  • Please note that the native dialogs for doing so vary by browser, operating system and the type of authenticator you are using.

Enter the integration dashboard#

integraion

  • Use the navigation bar to select “Integration”,or
  • Press the “Add New” button

Sign the CLA#

cla

  • Scroll down the page to Step 1, press the “Accept” button
  • Agree to the terms
  • Confirm that the CLA is signed

Add new OAuth2 Integration#

oauth

  • Enter a name for your application, website or service
  • Enter the callback URL for your application, website or service
  • Copy the Application ID and Application Secret and store in a safe place

Note

Your Application Secret is very important to protect, if you lose it or expose it accidentally, you will need to create a new one. So, please don’t check it into source control!**

Note

Your Application ID is a unique identifier used to describe your application to LoginID. The Application Secret is a secret you must keep safe and is used to authenticate the request when interacting with LoginID.**

Once you have gone through the above steps you should have received and saved the following:

Field Value
Domain https://exchange.domain
Client ID Auto generated client ID
Client Secret Auto generated client secret

Step 3 - Install Passport-OAuth2 Strategy#

Passport-OAuth2 is open source middleware that makes it easy for you to integrate your application with LoginID. You can learn more at https://www.npmjs.com/package/passport-oauth2.

Install the Package

$ npm install passport-oauth2

Step 4 - Set up your application and authorize#

Your application is going to need just a few things to get started. Configure the \$provider variable with the details from Steps 1 & 2.

passport.use(new OAuth2Strategy(
    {
        clientID: 'demoapp’, // The client ID
        clientSecret: 'demopass', // The shared secret, but keep in config!
        callbackURL: 'https://example.com/your-redirect-url/',
        authorizationURL: 'https://sandbox.loginid.io/hydra/oauth2/auth',
        tokenURL: 'https://sandbox.loginid.io/hydra/oauth2/token',
        scope: 'openid',
        state: base64url(JSON.stringify({blah: 'This is a test value'}))
    },
    function(accessToken, refreshToken, profile, cb) {
        console.log("Access token is: ");
        console.log(util.inspect(accessToken, false, null));

        if (profile) {
            user = profile;
            return cb(null, user);
        } else {
            return cb(null, false);
        }
    }
));

passport.serializeUser(function(user, done) {
    done(null, user);
});

passport.deserializeUser(function(user, done) {
    done(null, user);
});

app.get('/login', passport.authenticate('oauth2'));

app.get('/callback',
    passport.authenticate('oauth2', { failureRedirect: '/login' }),
    function(req, res) {
        // Before this code, the strategy's callback is called
        console.log("Returning home...");
        res.redirect('/');
    }
);
passport.use(new OAuth2Strategy(
    {
        clientID: demoapp, // The client ID
        clientSecret: demopass, // The shared secret, but keep in config!
        callbackURL: 'https://example.com/your-redirect-url/',
        authorizationURL: 'https://sandbox.loginid.io/hydra/oauth2/auth',
        tokenURL: 'https://sandbox.loginid.io/hydra/oauth2/token',
        scope: 'openid',
        state: base64url(JSON.stringify({blah: 'This is a test value'}))
    },
    function(accessToken, refreshToken, profile, cb) {
        console.log("Access token is: ");
        console.log(util.inspect(accessToken, false, null));

        if (profile) {
            user = profile;
            return cb(null, user);
        } else {
            return cb(null, false);
        }
    }
));

passport.serializeUser(function(user, done) {
    done(null, user);
});

passport.deserializeUser(function(user, done) {
    done(null, user);
});

app.get('/login', passport.authenticate('oauth2'));

app.get('/callback',
    passport.authenticate('oauth2', { failureRedirect: '/login' }),
    function(req, res) {
        // Before this code, the strategy's callback is called
        console.log("Returning home...");
        res.redirect('/');
    }
);

Scopes#

Please specify the scope parameter as openid, which facilitates an OpenID Connect integration with LoginID's authentication platform. As LoginID enables other capabilities on the platform, other scope types will be made available in the future.

Getting Help#

We’re happy to assist, if you have any questions please don’t hesitate to contact support@loginid.io

Do you have any specific requests for examples using other frameworks or programming languages? Contact us and let’s talk about bringing secure, private authentication in to your application, we have engineers on standby to discuss.

Known bugs and future features#

LoginID is currently in a development phase, there are some known bugs and currently unimplemented features we are working on. Here is a list to help you navigate around them, we really appreciate the help from our integration partners in discovering more features and bugs - thank-you!

Name Type As of (date) Description
MultipleCallbackURIs Bug Dec 17/19 Only the first referring URL entered during creation of credentials will be used
OversizedScreens Bug Dec 17/19 Login and Registration screens extend too tall on some displays
UndersizedInput Bug Dec 17/19 Some mobile screens do not display the entire helper text on input fields and concatenate
ReferringURLError Bug Dec 17/19 Login process only kicks back to referring URL if the user is already logged in to the dashboard
UnconnectedReports Future Dec 17/19 Reports are not currently connected to real data
UnconnectedBilling Future Dec 17/19 Billing section is not connected to anything at all
UnconnectedProfile Future Dec 17/19 You can not edit your profile details
UnconnectedSupport Future Dec 17/19 Support features are not complete. Please contact your account representative or email support@loginid.io for your support needs

PHP Integration#

This section of the document assumes that you are using PHP and Composer in your development environment. Additional independent configuration options and integration 16mechanisms will be described in the API Documentation that is still under development.

Step 1 - Define your Callback URL#

When the user authenticates themselves with LoginID (similar to authenticating with Google), LoginID will need to pass back control and information back to your servers. The Callback URL is the path that will be used to accomplish this and you will need to define it.

Callback URL https://exchange.domain/callback

At the callback endpoint you will receive the following parameters:

Code This is the authorization code to grant you access to an access token
Scope The scope used for the request
State Unique id for the state

Step 2 - Obtain your client keys#

In order to receive access to integrate LoginID you will need to create your client credentials. This is similar to the credentials you would create with Google to use Google authentication. This allows your servers to call LoginID services in a secure, authenticated fashion.

To obtain the client keys you will need to perform the following steps:

Create a new account#

new account

  • Navigate to https://sandbox.loginid.io/en/login and select the “Register a new account” option
  • Enter a username and hit the “Next” button
  • You will be prompted to authenticate using biometrics

Note

You must already have configured your own personal device for biometric authentication. The way that devices do this vary by browser, operating system and more.

Enter the integration dashboard#

integraion

  • Use the navigation bar to select “Integration”,or
  • Press the “Add New” button

Follow the steps provided#

Depending on the type of integration you are using, you will be taken through a few steps which will likely include:

  • Adding a new integration (press the green “Add integration” button)
  • Writing down your Organization ID (it will be lost if you don’t)
  • Agreeing to and signing a CLA
  • Selecting the type of integration you seek (OIDC or Native)
  • Providing your Callback URL and Application Name
  • Copying the Application ID and Application Secret and store in a safe place

Note

Your Application ID is a unique identifier used to describe your application to LoginID. The Application Secret is a secret you must keep safe and is used to authenticate the request when interacting with LoginID.

Once you have gone through the above steps you should have received and saved the following:

Domain https://exchange.domain
Application ID Auto generated client ID
Application Secret Auto generated client secret

Step 3 - Install OAuth2 Client using Composer#

OAuth2 Client is open source middleware that makes it easy for you to integrate your application with LoginID. It can be dropped in to your web-based application and supports authentication using many different strategies. You can learn more at https://oauth2-client.thephpleague.com.

Install the Package $ composer require league/oauth2-client

Step 4 - Install OAuth2 Client using Composer#

Your application is going to need just a few things to get started. Configure the $provider variable with the details from Steps 1 & 2.

<?php

Require_once 'vendor/autoload.php';

$provider = new \League\OAuth2\Client\Provider\GenericProvider([
   'clientId'       => 'demoapp',  // The client ID
   'clientSecret'   => 'demopass', // The shared secret, but keep in config!
   'redirectUri'    => 'https://example.com/your-redirect-url/',
   'urlAuthorize'   => 'https://sandbox.loginid.io/hydra/oauth2/auth',
   'urlAccessToken' => 'https://sandbox.loginid.io/hydra/oauth2/token',
   'scopes'         => 'openid'
]);

// If we don't have an authorization code then get one
if (!isset($_GET['code'])) {
    // Fetch the authorization URL from the provider; this returns the
    // urlAuthorize option and generates and applies any necessary parameters
    // (e.g. state).
    $authorizationUrl = $provider->getAuthorizationUrl();

    // Get the state generated for you and store it to the session.
    $_SESSION['oauth2state'] = $provider->getState();

    // Redirect the user to the authorization URL.
    header('Location: ' . $authorizationUrl);
    exit;
// Check given state against previously stored one to mitigate CSRF attack
} elseif (empty($_GET['state']) || ($_GET['state'] !== $_SESSION['oauth2state'])) {

    unset($_SESSION['oauth2state']);
    exit('Invalid state');
} else {

    try {

        // Try to get an access token using the authorization code grant.
        $accessToken = $provider->getAccessToken('authorization_code', [
         'code' => $_GET['code']
        ]);

        // We have an access token, which we may use in authenticated
        // requests against the service provider's API.
        echo $accessToken->getToken() . "\n";
        echo $accessToken->getRefreshToken() . "\n";
        echo $accessToken->getExpires() . "\n";
        echo ($accessToken->hasExpired() ? 'expired' : 'not expired') . "\n";
...
    } 
    catch (\League\OAuth2\Client\Provider\Exception\IdentityProviderException $e) {    
        // Failed to get the access token or user details.
        exit($e->getMessage());

    }
}

Refreshing your token#

You can request a refresh of your token without having to re-authorize, you can do so by using this process: https://sandbox.loginid.io/en/login

$provider = new \League\OAuth2\Client\Provider\GenericProvider([
    'clientId'       => 'demoapp',    // The client ID
    'clientSecret'   => 'demopass',   // The shared secret
    'redirectUri'    => 'https://example.com/your-redirect-url/',
    'urlAuthorize'   => 'https://sandbox.loginid.io/hydra/oauth2/auth',
    'urlAccessToken' => 'https://sandbox.loginid.io/hydra/oauth2/token'
]);

$existingAccessToken = getAccessTokenFromYourDataStore();

if ($existingAccessToken->hasExpired()) {
    $newAccessToken = $provider->getAccessToken('refresh_token', [
        'refresh_token' => $existingAccessToken->getRefreshToken()
    ]);

    // Purge old access token and store new access token to your data store.
}

Getting help#

We’re happy to assist, if you have any questions please don’t hesitate to contact support@loginid.io.

Note

Do you have any specific requests for examples using other frameworks or programming languages? Contact us and let’s talk about bringing secure, private authentication into your application, we have engineers on standby to discuss.

Known bugs and future features#

LoginID is currently in a development phase, there are some known bugs and currently unimplemented features we are working on. Here is a list to help you navigate around them, we really appreciate the help from our integration partners in discovering more features and bugs - thank-you!

Name Type As of (date) Description
MultipleCallbackURIs Bug Dec 17/19 Only the first referring URL entered during creation of credentials will be used
OversizedScreens Bug Dec 17/19 Login and Registration screens extend too tall on some displays
UndersizedInput Bug Dec 17/19 Some mobile screens do not display the entire helper text on input fields and concatenate
ReferringURLError Bug Dec 17/19 Login process only kicks back to referring URL if the user is already logged in to the dashboard
UnconnectedReports Future Dec 17/19 Reports are not currently connected to real data
UnconnectedBilling Future Dec 17/19 Billing section is not connected to anything at all
UnconnectedProfile Future Dec 17/19 You can not edit your profile details
UnconnectedSupport Future Dec 17/19 Support features are not complete. Please contact your account representative or email support@loginid.io for your support needs
ProviderParameter bug Mar 12/20 New parameter required for the league/oauth2-client GenericProvider (urlResourceOwnerDetails)
Untested release unknown Mar 24/20 This version of the document has been updated for an integration but the changes have not been verified.