Page History
When integrating Yellowfin with a host application, it is necessary to provide a seamless jump between the host application and the Yellowfin interface. This might include integrating the full Yellowfin UI, or embedding individual pieces of content within the host application. In either case, an existing Yellowfin session is required to suppress Yellowfin from prompting the user to login each time. This can be achieved with Yellowfin’s SSO services.
Yellowfin’s SSO end-point allows for generating a single-use token that allows the user to by-pass the user authentication screen in Yellowfin.
The standard use case is that a user will already be authenticated with the host application (where Yellowfin is integrated or embedded). When the user attempts to enter an area of the host application that requires Yellowfin, the host application can make a server-side call to Yellowfin to generate a single-use token. Once the token is retrieved, it can be added to either the Yellowfin logon URL, or embedded in JS API code. The user can then be redirected to the URL or a page with embedded content.
To bypass the standard Yellowfin login screen, the token can be added to this URL:
http://<yellowfin-server-address>/logon.i4?LoginWebserviceId=<tokenId>
Generating an SSO Login Token
A Login SSO token can be retrieved using the GET /api/login-tokens end-point (https://developers.yellowfinbi.com/dev/api-docs/current/#operation/createLoginToken ). The payload for this request is of the form:
{
"signOnUser": {
"userName": "admin@yellowfin.com.au",
"password": "test",
"clientOrgRef": "CLIENT1"
},
"loginParameters": [
"YFTOOLBAR=FALSE",
"ENTRY=VIEWDASHBOARD",
"DASHBOARDUUID=5678f33c-c666-4972-8976-9c489accf73b"
],
"noPassword": false,
"customParameters": "Some custom integration value"
}
The signOnUser attribute is required, the other attributes are optional. The contents of the signOnUser attribute will be the credentials of the user we are logging in. The clientOrgRef is only required when logging into a tenant.
The following examples return the SSO token that can be used to log a user into Yellowfin without prompting them for the username and password. This example uses the standard paradigm of using a REST Access Token.
Java | C# | Go | JavaScript | PHP | Python
Generating an SSO Login Token to access a Tenant
Providing a clientOrgRef will create a token for creating a user session in a tenant. If a clientOrgRef is not supplied, and the user is a member of multiple tenants, then that user will be shown the Client Organization selection screen during the login process. If the user is a member of a single tenant, the user will not be prompted to select a Client Organization during the SSO process.
The clientOrgRef should be populated with the tenant’s Client Organisation reference code, for the user to be logged into that tenant.
{
"signOnUser": {
"userName": "admin@yellowfin.com.au",
"password": "test",
"clientOrgRef": "CLIENT1"
}
}
The following examples return the SSO token that can be used to log a user into a Yellowfin tenant without prompting them for the username and password. These examples use the standard paradigm of using a REST Access Token.
Java | C# | Go | JavaScript | PHP | Python
Generating an SSO Login Token for targeted entry to a specific page
The loginParameters with the SSO payload allows options to be set for the new session that the token will create. This can be used to hide and show UI elements, set security parameters, and determine what page the user will land on when they login. This example payload shows that the user's entry will be a dashboard with the supplied dashboard UUID.
{
"signOnUser": {
"userName": "user1@yellowfin.com.au",
"password": "test"
},
"loginParameters": [
"ENTRY=VIEWDASHBOARD",
"DASHBOARDUUID=5678f33c-c666-4972-8976-9c489accf73b"
]
}
The following code examples will create a SSO token with a specified dashboard entry point:
Java | C# | Go | JavaScript | PHP | Python
Generating an SSO Login Token without a user password
The loginParameters with the SSO payload allows options to be set for the new session that the token will create. Enabling noPassword=true, allows for creating a session for a user without their password.
{
"signOnUser": {
"userName": "admin@yellowfin.com.au"
},
"noPassword": true
}
This can be used in scenarios where user passwords don’t need to be retained. This could involve assigning random UUIDs as passwords when creating new users. If the users are always entering the application via SSO (using the noPassword option), then their real password never needs to be known.
The noPassword option requires the Insecure login flag to be enabled in Yellowfin’s configuration database.
The following code examples illustrates how to create a session token without a user's password:
Java | C# | Go | JavaScript | PHP | Python
Perform SSO Logout / Destroy SSO created Session
A session that is created via SSO, can be destroyed using the DELETE /api/login-tokens/{tokenId} end-point (https://developers.yellowfinbi.com/dev/api-docs/current/#operation/deleteLoginToken ). When {tokenId} is the tokenId returned by the initial SSO login REST call.
The tokenId is different from the securityToken that is used to initialize the SSO session. The tokenId should be stored by an application that wants the capacity to end the session at a later point in time.
The following code examples illustrate how to destroy an existing session created via SSO Login, with a given tokenId:
Java | C# | Go | JavaScript | PHP | Python
Using a JWT token for SSO
Yellowfin has a in-built mechanism to consume a JWT token for authentication. This has less flexibility than using the REST API directly, but it does allow for the implementation of SSO (and on-boarding) to be achieved quite easily.
The JWT token holds all the information to SSO a user into Yellowfin. If a user has already been created, the JWT payload only needs to contain a userId, and SSO can be achieved. The JWT method can also onboard users if they do not exist, however additional information (like name and email address) need to also be provided in the JWT payload so that information can be used to create a new user.
Yellowfin’s JWT implementation supports multiple signing and encryption methods, to ensure that the payload is secure.
JWT can be enabled via the Authentication tab of the Configuration page. Options here allow for specifying attribute mappings between the JWT payload and the data that Yellowfin needs.
Toggle “JWT Single Sign On” to enable JWT functionality:
Provide mappings from your JWT token to attributes that Yellowfin needs:
If creating a custom JWT token, application code needs to generate the JWT token and sign or encrypt it with a supported algorithm. The website https://jwt.io/ provides a UI for creating JWT tokens manually for testing.
This screenshot from jwt.io shows the payload properties on the right and the resultant JWT token on the left.
The token on the left can be passed to Yellowfin via the below URL. This will act in a similar way to the SSO token, and log the user into Yellowfin, bypassing the username/password prompt.
http://<yellowfin-server-address>/JWTLogin.i4?jwtToken=<jwt-token>
JWT onboarding can also be enabled, and this will create a new user if a user defined within the JWT token does not already exist in Yellowfin (based on the supplied user Id). The JWT Token needs to include attributes required for creating a user if this feature is enabled.