Kit Configuration
Learn how Bright Kit is configured to enable Bright Energy to make requests.
Authorization
Authorization for Kit is dependent on several factors. As this is your integration built for use by Bright Energy, architecture, User country and security restrictions will all play a factor in deciding the authorization methods enabled.
There are two groups of authorization methods:
- User Authorization
- Data Layer Authorization
User Authorization
BankId (Sweden)
In Sweden the most well known login eID solution is BankId.
BankID is a common way to identify yourself in digital environments. You do not have to create accounts with passwords with different actors, and can instead use the same secure solution for everyone. Like showing your ID, but digitally.
In order for your end-users to trust the application and login securely, we relay all BankId API calls to your backend so the end-user will see your company name and certificate in the BankId app.
Test BankId
If you do not have a BankId for personal use already, please obtain a test bankId from: https://developers.bankid.com/test-portal/bankid-for-test
Afterwards you can test if it works at: https://test.bankid.com/
Get a BankId certificate
You must order a BankId certificate from one of the approved banks found at: https://www.bankid.com/en/foretag/kontakt-foeretag.
OpenId
OpenID is an easy and safe way for people to reuse an existing account and user profile from an identity provider, for example Apple, Google, or Microsoft to login to any OpenID-enabled applications and websites without creating a new registration and password. You choose the provider, such as Google and enter your Gmail address and password to login.
Requirements
- You must expose your
.well-known/openid-configuration
for Bright Energy to read. client_Id
,client_secret
andscope
needs to be sent to your Customer Success Manager in a secure manner.- You need to configure the following callbackUrl's:
Callback URL's | Purpose |
---|---|
https://my-organisation-name.production.getbright.se/v3/auth/my-organisation-name/callback | Production callback URL |
https://my-organisation-name.staging.getbright.se/v3/auth/my-organisation-name/callback | Staging callback URL |
https://mypagesURL/auth/my-organisation-name/callback | My Pages Production callback URL |
https://mypages.my-organisation-name.staging.getbright.se/v3/auth/my-organisation-name/callback | My Pages Production callback URL |
Only if you have a My Pages setup do you need My Pages callback URLs.
Learn more at: https://openid.net/developers/how-connect-works/
openId endpoints
The endpoints in openId are provided as examples so you can test your OpenID setup with Bright Kit. Please build your OpenID integration to the specification: https://swagger.io/docs/specification/v3_0/authentication/openid-connect-discovery/.
If you do not have an OpenId solution provider today, we recommend Signicat .
Signicat
Signicat is an all-in-one solution for using the country specific eID for your Users login. Read more at: Signicat Developer Hub to see what methods are included in each country and how to get started with your own Signicat account.
One-time code via email
If some of your Users cannot login with bankId we can enable an email login using a single use verification code. Please note that users should be uniquely identified with their email address and have access to a single Account only.
Data Layer Authorization
Bright Energy requires access to your entire data layer at any time regardless user interactions. This is due to the requirement to implement the Data Synchronisation for an optimal User experience.
API Key
The simplest method to implement is an apiKey header.
The API key must be environment specific, generated by the Organisation and able to be revoked and replaced in the event of a security exposure.
The header name can be anything, for example Ocp-Apim-Subscription-Key
and the correct value.
Bearer: Access Token
Using the Authorization header in combination with a valid access_token
generated from oauth or openId. It is possible to use a pre-generated JWT token that never expires, similar to an apiKey, but we recommend an oauth implementation to increase security.
IP Whitelist
Please whitelist the following IP addresses if required for accessing your Bright Kit.
- 46.254.9.239 (Cleura staging)
- 46.254.9.177 (Cleura production)
- 79.136.34.34 (Office VPN)
- 86.107.49.69 (Forward Proxy for all environments)
Variables
- stagingis the name of the environment Bright Energy will target when making requests.
- domainis the name of the domain you have deployed the Bright Kit implementation to.
- v1is the version of the Bright Kit being targeted.
- v1
Dates and Timestamps
Date Formats
All dates shall be strings formatted according to the ISO 8601 standard, including timezone definition:
-
2024-10-10T09:59:44+02:00
-
2024-10-10T09:59:44Z
Time Periods
Time periods are always set between a fromDate
and a toDate
as query parameters in the request. The resolution
parameter is used to structure the response data for graphs viewed in that resolution.
-
fromDate
is always required. If requesting real time data use this field only. -
toDate
is sometimes required. -
resolution
is sometimes included in the request.
Responses for time period requests
Response bodies shall always include a startDate
and endDate
to detail the time period of the data. In cases where you cannot supply the same time period as requested, provide startDate
and endDate
fields that match the response data.
Order of time series results
Responses which include values related to a startDate
and endDate
the data series should be returned chronologically. Do not send randomized results.
HTTP Response Status Codes
Implemented endpoints shall return the specified response status codes.
Any endpoint that is not implemented shall return the code 501 Not Implemented
.
WebViews
What is a WebView?
A WebView is a web browser that is embedded within an app.
Configuration
Before Bright Energy can make a Get WebView url request you will need to send us a list of WebViews you would like to be available in the app.
Each item in the list should include:
- View Name
- urlKey
(camelCasedKeyName)
- Value (camelCasedKeyValue or full URL string)
- App location for the WebView to be available to users
- openInBrowser
(boolean)(set to true to open in external Browser App instead)
WebView Flows:
Shared View:
- Bright Energy saves a
urlKey
value that corresponds with a finalUrl - termsAndConditions -> https://organisationDomain.com/termsAndConditions
- The finalUrl is rendered and Bright Energy does not make a Get WebView url request.
User Specific View:
- Bright Energy stores the name of the
urlKey
and uses it to make a Get WebView url request - termsAndConditions -> termsAndConditions
- We request Get WebView url with all the query parameters (userid, locationid etc...)
- The Organisation computes a finalUrl and responds to the Get WebView url request
- Bright Energy renders this finalUrl as a WebView in the app.
Example:
WebViews can be used for opening webpages for user actions not currently supported by the app such as the renewal of an agreement.
You have previously given us a view name called Account Renewal
with the urlKey accountRenewal
to be located inline with existing agreements for the account.
Bright Energy will then request your Get WebView url endpoint with the following structure:
https://{kitEnvironment}.{kitDomain}/{kitBasePath}/webview?accountid={accountId}&clientId=app&language=sv&urlkey=accountRenewal&serviceId={serviceId}&userId={userId}
.
Your response body has the computed finalUrl set as the value of the body parameter with key url
. The finalUrl should include everything needed to load the WebView (authentication, tracking, etc...) so that Bright Energy can successfully render the WebView for the user.
Updated 35 minutes ago