Introduction to Assently CoreID
The Assently CoreID Client is a javascript plugin that allows your users to securely authenticate with electronic identification (eID) without any of the hassle. CoreID Client works in both your app and your website.
Let us worry about integrations, security, browser support and maintenance while you focus on creating value for your users.
Contact us at info@assently.com to get started.
CoreID also supports SAML, more info below.
How does it work?
Add our javascript to your website/app, generate a token, configure with a few lines of code and you're good to go!
CoreID securely communicates with our servers which handle the integrations with the different eID Providers.
Check out our quick start guide to see how to get started with CoreID.
Languages
The client is localized in the following languages:
- English
- Finnish
- Norwegian
- Swedish
Security
All traffic is encrypted via SSL/TLS.
Information is sent via JSON web tokens encrypted with HS256.
Messages are decoded and verified with shared secrets.
Getting started
Follow our guide to get started in authentication or use this guide for signing!
Technical Details
The client is 100% JavaScript and uses XMLHttpRequests and embeds via an iframe.
Test
The test client will target the test environment of our API and the providers (if applicable).
Make sure to use your test account secrets.
Please refer to each providers documentation on how to test authentication with a specific provider.
<script src="https://coreid-test.assently.com/embed/coreid.js"></script>
Production
Only real persons or subjects can authenticate.
Make sure to use your production secrets.
<script src="https://coreid.assently.com/embed/coreid.js"></script>
Message formats
We use JWT (JSON Web Tokens) for secure communication between our server and your clients.
If you want to use SAML please contact us at info@assently.com for more information.
Client API and Configuration
Functions
init({ config [object], token [string], callback [function] })
Initializes the CoreID client, must be called before start()
.
var config = {};
var myCallback = function(data) {};
coreid_client.init({
config,
'YOUR TOKEN HERE',
myCallback
});
start()
Shows the CoreID client to the user.
coreid_client.start();
close()
Hides the CoreID client from the user.
coreid_client.close();
Configuration
token - String, undefined
The secret sauce!
See the this section for information on how to generate your auth token.
token: '😎✌️🏽'
callback - Function, undefined
This function will be invoked by the client at the end of transactions, both for success and fail or in case of an error.
// a basic example
callback: function(data) {
if (data.success === true) {
// sweet! let's validate and keep this token for whatever
$.post('api/token/validate', data.token, handleSuccess, handleError);
} else if (data.type === 'failed') {
console.log('authentication failed', data.errorMessage);
} else if (data.type === 'cancelled') {
console.log('user closed the app');
} else if (data.type === 'error') {
console.log('an error occurred', data.errorMessage);
}
}
The callback receives an object parameter that can have the following properties
// A successful transaction object would look like this
{
success: true, // always exists if authentication succeeded
token: '#####', // JWT that contains identity token, validate this!
provider: 'se-bankid', // provider that user authenticated with
type: 'authenticated', // transaction type
transactionId: '####' // is present for most of the providers, use this as a reference when contacting Assently Support
}
// An unsuccessful transaction object
{
type: 'failed', // if authentication failed
provider: 'se-bankid', // provider used
errorMessage: '' // information about the possible error
}
// User closed or cancelled CoreID client,
// can happen after authentication is successful
{
type: 'cancelled',
errorMessage: 'USER_UI_CANCEL
}
// An error occurred, which usually indicates
// a wrong configuration
{
type: 'error',
errorMessage: '' // details about the error,
success: false
}
config.allowedEids - String[], ['*']
This option allows you to define which eID Providers you want to enable.
The default value ['*']
will enable all providers.
[
'*', // All
'fi-mv', // Finnish Mobiilivarmenne
'fi-tupas', // Finnish Tupas
'fi-vrk', // Finnish VRK
'no-bankid', // Norwegian BankID
'no-bankid-mobile', // Norwegian BankID mobile
'se-bankid', // Swedish BankID
'se-telia-osif' // Swedish Telia
'dk-nemid' // Danish NemID
]
Note that you need to have at least the same eIDs in your token since token parameters define authorization to the CoreID API.
config.location - String, undefined
This option configures the default country view when starting the client.
Overridden by config.provider
.
If undefined
the user will first be presented with a view to select country.
'se' // default view will display the Swedish providers
'fi' // ... Finnish providers
'no' // ... Norwegian providers
config.mode - String, undefined
Sets the mode. Depending on the mode only to that mode available eID's will be shown to the user.
'auth' // Authentication mode
'sign' // Signing mode
config.provider - String, undefined
Sets the default view to the specific provider, overrides default view set by the location
option.
'fi-mv' // Finnish Mobiilivarmenne
'fi-tupas' // Finnish Tupas
'fi-vrk' // Finnish VRK
'no-bankid' // Norwegian BankID
'no-bankid-mobile' // Norwegian BankID mobile
'se-bankid' // Swedish BankID
'se-telia-osif' // Swedish Telia
'dk-nemid' // Danish NemID
config.providerSettings - Object, undefined
This object allows for provider-specific settings, note that not all providers have this option.
Available configurations:
{
'se-bankid': {
// if set to false the client will not try to open the native Swedish BankID app.
// there is an event emitted with all the info you need,
// see separate section
autoStart: true, // default
// customize the 'redirect'-parameter to Swedish BankID app
// see Swedish BankID's documentation for more information
redirectUrl: 'someURI'
},
'fi-tupas': {
// if set, will sort Tupas banks alphabetically, in ascending or descending order
// if not set, will retain its original order
sort: 'asc', // or 'desc'
// use include to specify exactly which banks you want to be available
// 'include' will make sure the client only ever lists your selected banks
// for a list of banks and their IDs, see below
include: [''],
// use exclude to specify banks to be excluded
// this option will be ignored if include-option is specified
exclude: [''],
}
}
Tupas banks:
[
{ Id: "08ACDDE6-2C38-418B-ACC7-67CEF0FD24A8", BankName: "Nordea"},
{ Id: "5A57F571-C625-46D8-A721-7F23CBF0A9AE", BankName: "Danske Bank"},
{ Id: "4885E8D2-C6AC-4732-A3FF-132C4CA9977B", BankName: "Aktia "},
{ Id: "6C583D7B-1C6F-4CBC-9BE9-FA9C26CDD4F1", BankName: "S-Pankki"},
{ Id: "F0EA5D03-E63D-4A0D-84DC-EFEA0FA91306", BankName: "LähiTapiola"},
{ Id: "916194F1-A31A-4DBD-B481-EDDD1F5A311D", BankName: "Handelsbanken"},
{ Id: "1BD11C49-65BF-4DA3-B609-60414EBD8F1F", BankName: "OP"},
{ Id: "8D6C10E6-8C82-4FD2-B55E-E881DA7411B9", BankName: "Säästöpankki"},
{ Id: "2625E44A-3E08-4323-8B4E-D4E0AD1C2615", BankName: "POP Pankki"},
{ Id: "F82E50A2-A778-44CA-827C-6B062477267C", BankName: "Ålandsbanken"}
]
config.showTitle - Boolean, true
showTitle: true
Setting to show the title inside the frame. Defaults to true
.
config.sign - Object, undefined
The sign object is mandatory in sign
mode. All properties are required!
{
title: 'Your title', // The title
data: 'Your document', // The data you want to sign
type: 'text' // The format of data. The only allowed value is text, but more types will be added in the future.
Events
The client also emits some events via PostMessage that developers can subscribe to.
All events are of type MessageEvent
and are dispatched at the target window, subscribe like so:
window.addEventListener('message', function(e) {
// check e.data.type
});
None of these events are required to be handled by the developer, they are provided for your convenience.
bankId-startClient
MessageEvent {
data: {
type: 'bankId-startClient', // event type
autoStartToken: 'TOKEN', // needed to start the app correctly
transactionId: 'guid' // Assently generated transaction id
}
}
This event fires when the Swedish BankID app is to be opened.
Contains data to allow developers to start the Swedish BankID app by their own accord.
More about the JWT Auth Token
JWT Basics
Take a couple of minutes and read a little bit at https://jwt.io/introduction/.
JWT Libraries
Find a library at https://jwt.io/#libraries or google a library that supports your platform.
Create the JWT
Use the library to define your claims, specify that you want to use HMAC SHA256 and sign it with the auth secret provided by Assently.
Claims
There are 7 claims that are required, e.g.:
{
"jti": "3bfae357-c056-4567-b15d-ca657fbdg866", //A unique token identifier
"iss": "acme", //The customer account name (as issued by Assently)
"aud": [
"se-bankid",
"fi-mv"
],// see the description of the claim below
"iat": 1467217112,//Identifies the time at which the JWT was issued.
"exp": 1467218912, //Identifies the expiration time on or after which the JWT is not accepted for processing.
"hst": "https://acme.com", //The URL of the host including scheme (and if differs from default, port).
// Custom display names must be registered with Assently beforehand
// Valid displaynames are
// "Assently" for production
// "Test av Mobilt BankID" for test
"dnm": "Acme" //see description below
}
Descriptions for each claim can be found below.
"jti"
Name
JWT id
Description
A unique token identifier
Format
GUID
Example
"3bfae357-c056-4567-b15d-ca657fbdg866"
Mandatory
Yes
"iss"
Name
Issuer
Description
The customer account name (as issued by Assently)
Example
"acme"
Mandatory
Yes
"aud"
Name
Audience
Description
Should contain the eID Providers you want your users to choose from.
Note: Make sure the eID's in the token at a minimum includes the "allowedEids" configuration in the client.
Available eID's:
- all - All available eID's
- se - All Swedish eID's
- se-bankid - Swedish BankID
- se-telia-osif - Swedish Telia
- fi - All Finnish eID's
- fi-tupas - Finnish Tupas
- fi-mv - Finnish Mobiilivarmenne
- fi-vrk - Finnish VRK
- no - All Norwegian eID's
- no-bankid - Norwegian BankID
- no-bankid-mobile - Norwegian BankID on mobile
- dk - All Danish eID's
- dk-nemid - Danish NemID
If using multiple eID's, the "aud" value is an array of strings. If using a single eID the "aud" value can be a single string value.
Example
["se_bankid", "fi-mv"]
Mandatory
Yes
"iat"
Name
Issued at
Description
Identifies the time at which the JWT was issued.
Format
Unix timestamp
Example
1467217112
Mandatory
Yes
"exp"
Name
Expiration time
Description
Identifies the expiration time on or after which the JWT is not accepted for processing.
Format
Unix timestamp
Example
1467218912
Mandatory
Yes
"hst"
The host that is using the service.
Name
Embed host
Description
The URL of the host including scheme (and if differs from default, port).
Format
URL
Example
"https://www.acme.com"
Mandatory
Yes
"dnm"
Name
Display name
Description
The text (usually company name) to be displayed on the end user's display during authentication.
Note that a custom display name must be registered with Assently in advance. If no display name is registered, "Assently" will be used as default.
In test environment with se-bankid the display name must be specified "Test av Mobilt BankID".
Example
"Acme"
Mandatory
Only for se-bankid and fi-mv
More about the JWT Identity Token
When a user has successfully authenticated you will receive a JWT in the callback.
1. Verify the signature of the token
To be sure nothing has been tampered with, you must verify the signature of the token with a shared secret.
HMACSHA256(
base64(header) + '.' + base64(payload),
secret
)
2. Validate the claims of the token
If any of these claims are invalid, you must reject the JWT.
iss
Should match the hostname of the embed script path.
aud
Should match your issuer name provided by Assently
exp
Must be in the future. The value will be 60 minutes in the future from the time it is generated.
3. Done!
The JWT payload contains claims regarding who the authenticated subject is.
How you use this information is up to you.
"sub"
Identifier of the subject
Name
Subject
Description
Can be a national id number, birthdate or phone number.
Example
"19800101"
Mandatory
Yes
"sub.national_id"
The subjects' national id number.
Name
National ID
Description
The format can vary depending on eID Provider.
Example
"198001011234"
Mandatory
No
"sub.family_name"
Name
Family name
Description
Last name, surname, or family name of the subject.
Example
"Miller"
Mandatory
No
"sub.given_name"
Given name of the subject.
Name
Given name
Description
Some providers also include middle name(s).
Example
"Frank"
Mandatory
No
"sub.full_name"
Full name of the subject
Name
Full name
Description
Includes first name(s) and last name(s).
Example
"Frank Miller"
Mandatory
No
"provider"
Name
Provider
Description
The name of the eID Provider that was used to conduct the authentication.
Example
"se-bankid"
Mandatory
Yes
"provider.data"
Name
Provider data
Description
All personal information related to the subject as received from the eID Provider. This is usually an x.509 certificate that we send along in its raw form encoded as a base64 string.
Format
base64 encoded string
Mandatory
Yes
"jti"
Name
JWT id
Description
The unique identifier of the token.
Example
"66619e7a-e34b-4f76-85df-71634328d3g1"
Mandatory
Yes
"iss"
Name
Issuer
Description
The token issuer.
Example
"coreid-test.assently.com"
"coreid.assently.com"
Mandatory
Yes
"aud"
The intended receiver of the token.
Name
Audience
Description
Contains your customer account name.
Example
"some-company-name"
Mandatory
Yes
"iat"
Name
Issued at
Description
Identifies the time at which the JWT was issued.
Format
Unix timestamp
Example
1466429950
Mandatory
Yes
"exp"
Name
Expiration Time
Description
Identifies the expiration time on or after which the JWT is not accepted for processing.
Format
Unix timestamp
Example
1466433550
Mandatory
Yes
"auth_jti"
The JWT id from the auth token used in the same session.
Name
Auth Token JWT id
Description
This claim can be used for comparison with the "jti" claim in the auth token.
A match verifies that the identity received is related to the original request.
Example
"3bfae357-c056-4567-b15d-ca657fbdg866"
Mandatory
Yes
Supported eID Providers
eID Provider |
Country |
Authentication |
Signing |
Telia |
Sweden |
yes |
no |
BankID |
Sweden |
yes |
no |
Tupas |
Finland |
yes |
no |
Mobiilivarmenne |
Finland |
yes |
no |
VRK |
Finland |
yes |
no |
BankID |
Norway |
yes |
text only |
BankID Mobile |
Norway |
yes |
text only* |
NemID |
Denmark |
yes |
no |
* Due to limitations in SIM Toolkit on mobile phones BankID Server has to filter and prepare the “text to sign” before sending it to the mobile phone. The following ASCII input characters are accepted; [0-9] [a-z] [æ] [ø] [å] [A-Z] [Æ] [Ø] [Å] [CR] [LF] [#] [$] [%-&] [(-?] [@] [¡] [£] [¤] [¥] [§] [¿] [Ä] [Ç] [É] [Ñ] [Ö] [Ü] [ß] [à] [ä] [è] [é] [ì] [ñ] [ò] [ö] [ù]. The maximum length for signing data is approx. 38 characters.
Working with the eID Providers in different Environments
Test Environment
The CoreID Test Environment connects with the different eID Providers' test services. You have the option to use to this environment if you want to try out one or more eID Provider using test certificates. Since each eID Provider have different ways of authenticating users (software, mobile, etc.) they way to get a hold of test certificates are also specific to each eID Provider.
Swedish BankID (Svenskt BankID)
To test Swedish BankID you need to download a test certificate at
Certificates are available both for mobile and computer use.
Instructions on how to install the BankID software and the test certificate are found at
Note that the claim "dnm" (Display Name) in the Auth Token has to be set to "Test av Mobilt BankID" in the test environment.
Swedish Telia
Telia uses a software called Net iD that can be downloaded here:
Get test certificates at:
Net iD only works in Firefox in Windows.
Snippets
More snippets coming soon. For now, C# is all you get.
C# Code Snippets
Auth Token Creation
This C# snippet use System.IdentityModel.Tokens.Jwt library.
public class AuthTokenService
{
/// <param name="displayName">Display name is required for Swedish BankID and Finnish Mobiilivarmenne and should be added to token as a "dnm" claim.</param>
/// <param name="embedHost">The URI of the host. Required claim, should be added as "hst"</param>
/// <param name="accountId">Customer account id at Assently</param>
/// <param name="secret">The secret that is used to sign the JWT. Provided by Assently</param>
/// <returns>Encoded JWT string</returns>
public string CreateToken(string displayName, string embedHost, string accountId, string secret)
{
// The time at which the token was issued.
var issuedAt = (int)(DateTime.UtcNow.Subtract(new DateTime(1970, 1, 1))).TotalSeconds;
var claims = new List<Claim>()
{
new Claim("dnm", displayName),
// "jti" (Jwt Id) is a mandatory token identifier. Should be a GUID4.
new Claim("jti", Guid.NewGuid().ToString()),
new Claim("hst", embedHost),
new Claim("iat", issuedAt.ToString()),
// It is possible to add each implementation as a separate claim
new Claim("aud", EidAccess.SwedishBankId),
new Claim("aud", EidAccess.FinnishMobiilivarmenne),
new Claim("aud", EidAccess.NorwegianBankId),
// Or add all swedish
new Claim("aud", EidAccess.AllSwedish),
// Or all
new Claim("aud", EidAccess.All)
};
// Expiration time for the token, this is how long the token can be used to start an authentication session.
var expires = DateTime.UtcNow.Add(TimeSpan.FromMinutes(30));
var jwt = new JwtSecurityToken(
issuer: accountId,
claims: claims,
expires: expires,
signingCredentials:
new SigningCredentials(
new InMemorySymmetricSecurityKey(Encoding.UTF8.GetBytes(secret)),
"http://www.w3.org/2001/04/xmldsig-more#hmac-sha256",
"http://www.w3.org/2001/04/xmlenc#sha256"
)
);
var jwtHandler = new JwtSecurityTokenHandler();
return jwtHandler.WriteToken(jwt);
}
}
Auth Token Validation
This C# snippet use System.IdentityModel.Tokens.Jwt library.
public class IdentityTokenService
{
public JwtSecurityToken ValidateToken(string token)
{
var configuration = ConfigurationManager.AppSettings;
var tokenHandler = new JwtSecurityTokenHandler();
var secret = configuration["IdentitySecret"];
var keyBytes = Encoding.UTF8.GetBytes(secret);
var tokenValidationParameters = new TokenValidationParameters()
{
ValidateIssuerSigningKey = true,
IssuerSigningKey = new InMemorySymmetricSecurityKey(keyBytes),
ValidateIssuer = true,
ValidIssuer = configuration["Issuer"],
ValidAudience = configuration["AccountId"],
ValidateAudience = true,
ValidateLifetime = true,
ClockSkew = TimeSpan.Zero,
LifetimeValidator = (before, expires, jwttoken, validationParameters) =>
{
var now = DateTime.UtcNow.Add(validationParameters.ClockSkew);
if (before.HasValue && now < before.Value)
{
return false;
}
if (expires.HasValue && expires <= now)
{
return false;
}
return true;
}
};
SecurityToken validatedToken;
tokenHandler.ValidateToken(token, tokenValidationParameters, out validatedToken);
return validatedToken as JwtSecurityToken;
}
public bool ValidateJwtId(HttpCookie cookie, JwtSecurityToken identityToken)
{
var authToken = new JwtSecurityToken(cookie.Value);
var authJwtId = authToken.Claims.First(c => c.Type == "jti").Value;
var identityTokenAuthJwtId = identityToken.Claims.First(c => c.Type == "auth_jti").Value;
if (authJwtId == identityTokenAuthJwtId)
{
return true;
}
return false;
}
}
CoreID via SAML
Instead of using the CoreID javascript client, customers can use SAML to communicate with CoreID. This setup is made possible with an intemediate component called CoreID Gateway. CoreID Gateway acts as an Identity Provider (IdP) whereas Customers act as Service Providers (SP).
CoreID Gateway supports branding such as using custoer specific logos.
Communication scheme
The architecture from a high level looks like this:
Customers (SP) <-> CoreID Gateway (IdP) <-> CoreID <-> eID Providers
SAML Web Demo