Page History
...
The JWT entry point can also be used to provision a user if the user does not exist.
Styleclass | ||
---|---|---|
| ||
Activate JWT Single Sign On
...
- From the Yellowfin burger bun menu in the top left corner, click on Administration, then Configuration
- Click on the Authentication tool (the lock), then on Authentication Method
- Click on the toggle for JWT Single Sign On to enable it
A new section called JWT Configuration will appear. This is where everything related to JWT SSO is configured: - Click on JWT Configuration to expand the section. Each of the options is described in the tables below.
horizontalrule |
---|
Styleclass | ||
---|---|---|
| ||
Configure database options for JWT SSO
The JWT Configuration section of Yellowfin contains a variety of settings for implementing JWT SSO to provide you with as much flexibility as possible. You can choose to include the bare minimum, as indicated in the table and instructions below, or customize the token to include additional details according to your needs.
Click on JWT Configuration to expand the section. Each of the options is described in the tables below.
Parameter name | Parameter description | Required? | Default |
---|---|---|---|
JWT Token Delivery Mechanism | This radio button defines how the JWT token is retrieved — Cookie or URL Parameter. If Cookie is chosen, the JWT token will be fetched from the cookie named in the JWT Cookie Name field.
| No | URL Parameter |
JWT Cookie Name | This field only appears when the JWT Token Delivery Mechanism field is set to Cookie. This parameter defines the name of the cookie used. | No | None |
JWT Validation Key | This is the secret key for verifying the signature of the JWT token. This is a plain text secret. A binary key can be passed by encoding the secret in Base64. In this case, the Binary Validation Key field should be set to Plain Text. If you choose to use this, make sure you click the Update Password button after you’ve typed your secret key. Type the same secret key when creating your JWT token. | Yes | None |
Binary Validation Key | By default, this parameter is set to Plain Text. For added security, select the Base64 Encoded option. | No | Plain Text |
JWT Signature Verification Algorithm | By default, this setting is set to use the HMAC256 algorithm. Options are: Other options include: HMAC384, HMAC512 , RSA256, RSA384, RSA512, ECD256, ECD384 and ECD512. | No | HMAC256 |
JWT Issuer | This parameter validates the Issuer attribute in the JWT token, if one exists. If set, the value of this field will be compared to the Issuer field in the JWT token, and token verification will fail if they don’t match. | No | None |
JWT User Id Attribute | This parameter provides the Yellowfin UserId. | Yes | None |
JWT Client Reference Id Attribute | This parameter provides the location of the Client Reference Id of the client org that the user belongs to. Normally, this is set to ‘1’ for Yellowfin instances that have no related client orgs. | No | None |
SSO Entry Options | This parameter allows custom data that can be passed via the CustomParameters option on an SSO web service takes the JWT attribute that holds comma-separated web service session parameter values to be passed to the session created by the JWT SSO process. This is not attribute-based, so it applies to all users. See the Customize Data with CustomParameters and Parameters section for more details and an example. | No | None |
SSO Custom Session Variable Attribute | This parameter allows options that can be passed via the Parameters option on an SSO web service call to be passed to the session created by the JWT SSO process. This is attribute-based and can apply to individual users. See the Customize Data with CustomParameters and Parameters section for more details and an example. | No | None |
JWT Onboarding | This toggle enables a new user to be provisioned at their first login attempt if they don’t already exist. | No | Off |
...
horizontalrule |
---|
Styleclass | ||
---|---|---|
| ||
Database Options for JWT Onboarding
...
Parameter name | Parameter description | Required? | Default |
---|---|---|---|
First Name Attribute | The parameter defines the name of the JWT attribute for fetching the first name for a new user. Set this to First to automatically provision new users when they first try to login. | Yes | None |
Surname Attribute | The parameter defines the name of the JWT attribute for fetching the last name for a new user. Set this to Last to automatically provision new users when they first try to login. | Yes | None |
Email Attribute | The parameter defines the name of the JWT attribute for fetching the email address for a new user. This is used as a user’s username when logging in to Yellowfin. Set this to UserId to automatically provision new users when they first try to login. | Yes | None |
Language Attribute | The parameter defines the name of the JWT attribute for fetching the language code for a new user. | No | System default |
Password Attribute | The parameter defines the name of the JWT attribute for fetching the password for a new user. | No | Random password (32 alphanumeric string) |
Role Attribute | This parameter defines the name of the JWT attribute for fetching the role for a new user. If omitted, the default role will be given to the new user. | No | Whatever has been set as the default role (see https://wiki.yellowfinbi.com/display/yfcurrent/Roles) |
Fallback Role | This dropdown list provides the means of selecting a fallback role if the role entered in the Role Attribute field is not available at the time of provisioning a new user. | No | Whatever has been set as the default role (see https://wiki.yellowfinbi.com/display/yfcurrent/Roles) |
...
Styleclass | ||
---|---|---|
| ||
...
Create JWT tokens for use with Yellowfin
...
- Visit your preferred JWT token creator (in this example, we’ve used https://jwt.io/)
- At a minimum, add a username to the Payload section on the right
This should match whatever you’ve included in the JWT User Id Attribute field of Yellowfin: - If you’ve used a secret key in the Yellowfin field JWT Validation Key, type the same key into the text field in the signature section in the bottom right
For info, the colour coding on the left indicates how the JWT token is formulated. - Copy the encoded token on the left
- At the end of your Yellowfin URL, add the JWT token login and query string:
JWTLogin.i4?jwtToken= - At the end of the query string, paste the encoded token
The user you specified in the JWT payload will now be automatically logged in.
...
horizontalrule |
---|
Styleclass | ||
---|---|---|
| ||
Create a cookie containing a JWT token
...
- In the JWT Configuration area of Yellowfin, click on the radio button to select Cookie for the JWT Token Delivery Mechanism field
Notice that there’s a new field for JWT Cookie Name - In JWT Cookie Name, enter a cookie name
- In your browser, open the Developer Tools console and use the tools to display the existing cookie
- Use the Developer Tools of your browser to add a new cookie, making sure you:
- match the name to the JWT Cookie Name field in Yellowfin
- copy the encoded JWT token from the tool you used to create your token and paste it into the Value column for your new cookie
- Enter the JWT login URL to access your instance of Yellowfin (for example, http://localhost:8080/JWTLogin.i4).
horizontalrule |
---|
Styleclass | ||
---|---|---|
| ||
Customize data with CustomParameters and Parameters
If you already take advantage of the CustomParameters and Parameters options on an SSO web services call, these can also be added to your JWT token by using the fields SSO Entry Options Attribute and SSO Custom Session Variable Attribute.
SSO Entry Options Attribute
The SSO Entry Options Attribute field allows custom data per user that can be passed via the CustomParameters option on an SSO web service to be passed to a session created by the JWT SSO process. This is not attribute - based, so it applies can be applied to all users. individual users.
The SSO Entry Options Attribute field allows custom session variables to be set on a per-session basis when using JWT Single Sign On. The attribute can contain webservice SSO Session Options that will be applied to the session created by the JWT SSO process.
For example, if you want all your users a user to see their favourite reports, dashboards, stories etc. and so on when they login, you could use create a JWT attribute called SsoOptions with the TIMELINE and DISABLEHEADER parameters (or any others listed on the Defining Login Session Options wiki page). We’ll use these for our example belowWhen you place the JWT attribute name in the SSO Entry Options Attribute field, the parameters within are applied to that specific user.
- In the JWT Configuration area of Yellowfin, locate the SSO Entry Options field
- Enter any parameters, separated by commas, that you wish to use
In our example below, we’ve used ENTRY=TIMELINE,DISABLEHEADER=TRUE - Attribute field
- Type the name of your JWT attribute
- Click Click on the Save button to save your changes
You can test that your changes worked by logging in using your JWT token and checking that the login options you’ve specified are displayed.horizontalrule
Styleclass | ||
---|---|---|
| ||
...
SSO Custom Session Variable Attribute
...
In Yellowfin, the only requirement is to add those details to the SSO Custom Session Variable Attribute field. horizontalrule
Styleclass | ||
---|---|---|
| ||
...