Page tree
Skip to end of metadata
Go to start of metadata

This SSO implementation is a custom proprietary implementation provided by GoodData. This implementation is based on the PGP key pair exchange, and allows your application to sign in an existing GoodData user. The authentication is done not by username and password but by generating a session-specific token using a pair of PGP keys.

Depending on your current situation and use case, the GoodData PGP SSO is sometimes easier to implement than SAML SSO.

Example Use Case: Embedding GoodData

You can embed a report or dashboard into your application using the following code:

<iframe src="https://secure.gooddata.com/gdc/account/customerlogin?sessionId=GENERATED-STRING&serverURL=YOUR-SSO-PROVIDER&targetURL=TARGET-GOODDATA-URL"/>

 

Your hostname is secure.gooddata.com by default. If your organization is white-labeled, use the hostname of your white-labeled instance.

Here are the parameters:

ParameterDescription
sessionIdThis parameter must be dynamically generated, based on the user you want to authenticate.
serverURLThis value corresponds to the ssoProvider parameter used in the User Provisioning API.
targetURLThe URL to the dashboard, report or any other page you want to embed. The URL is relative to the GoodData server starting with “/”.

 

The following picture shows the whole authentication process:

Implementation Process

A complete implementation requires actions on both sides, yours and GoodData’s. We at GoodData deploy your public key and SSO provider configuration. You on your side implement a login mechanism that leverages our login resource.

The whole process usually takes few working days. Here are the basic steps:

  1. You send a request to create a SSO provider to support@gooddata.com.

  2. GoodData deploys your SSO provider to the production environment. You will receive this unique SSO parameter so that you can use it in user provisioning. This parameter is what we call SSO Provider in the user provisioning API.

    Review the prerequisites for using the user provisioning. Only an organization administrator can create or modify a user with the ssoProvider parameter specified.

  3. You set up your SSO environment.

Step 1. You send a request to create a SSO provider.

In your request, include your public PGP key. If you need to generate a new PGP key pair, see How to Generate Public-Private Key Pair. Do not delete the PGP header and footer (BEGIN/END) from the public key that you are sending.

Step 2. GoodData deploys your SSO provider to the production environment.

GoodData takes care of this step. We will let you know.

Step 3. You set up your SSO environment.

Complete the following steps. You have to dynamically generate a sessionId parameter.

  1. Create a specific JSON file.
  2. Sign this JSON file using the private part of your key that you sent to GoodData.
  3. Encrypt the result using the GoodData public key.
  4. HTML-encode the encrypted result.
  5. Assemble the final URL.

Example: GoodData Ruby SDK

# encoding: utf-8
require 'gooddata'
require 'pp'
client = GoodData.connect_sso('end.user@gooddata.com', 'SSO_PROVIDE_NAME')
pp client.user.json

Example: command line

1. Create a specific JSON file.

Timestamps are in seconds.

 

{"email": "end.user@domain.com","validity": 123456789, "notBefore": 11515111, "notOnOrAfter": 11515211}
ParameterDescription
emailCorresponds to a user account set up in GoodData with SSO permissions. This email is used for logging in through the SSO Login resource. The email is case-sensitive: User@domain.com is not the same as user@domain.com.
validityA date in UTC timezone (UNIX timestamp format and INTEGER data type) when the generated token expires. It must be set from a minimum of +10 minutes from present up to a maximum of 36 hours from present.
notBeforeA UNIX timestamp that specifies the earliest instant in time when the login session begins being valid.
notOnOrAfterA UNIX timestamp that specifies the instant in time when the login session expires.

 

The notBefore and notOnOrAfter fields are optional. However, we strongly recommend that you use them because they minimize a potential abuse of a login session. These fields ensure that a login session is valid within the specified period of time only (and it must not last longer than few minutes).

 

2. Sign the JSON file using the private part of your key.

Do not use the --clearsign option.

gpg --armor -u pgpOwner.user@domain.com --output signed.txt --sign json.txt

 

3. Encrypt the result using the GoodData public key.

Download the public key from gooddata-sso.pub.

gpg --armor --output enc.txt --encrypt --recipient security@gooddata.com signed.txt

 

4. HTML-encode the encrypted result.

Use your preferred programming language to encode the encrypted results.

 

5. Assemble the final URL.

https://secure.gooddata.com/gdc/account/customerlogin?sessionId=GENERATED-STRING&serverURL=YOUR-SSO-PROVIDER&targetURL=TARGET-GOODDATA-URL

Additional information for PGP-based SSO

SSO Security

Supported Encryption Algorithms

Public keyRSA, RSA-E, RSA-S, ELG-E, DSA
Cipher3DES, CAST5, BLOWFISH, AES, AES192, AES256, TWOFISH

 

SSO session duration

When an SSO session is initiated via login, the initiating application can define the length of the session token in the JSON.

This session duration is defined using the validity parameter. The validity parameter must be set as a UNIX time code that is a minimum of +10 minutes from present up to a maximum of 36 hours from present.

The header of the response to the login request contains a super-secure token (SST), which defines how long the session can last regardless of whether a user is active or not. If the SSO user is still logged in to the GoodData platform at the moment when the SST expires, the GoodData application stops responding.

To renew the token, refresh the parent page. This lets you log in back to the GoodData platform, and starts a new GoodData session over SSO.

You must control your PGP key validity and update it before it expires.

Troubleshooting

Dashboard not found

This error occurs only in Safari while SSO integration works fine in Chrome and Firefox.

Solution: URL-encode the targetURL parameter. Make sure it does not include the # character.

Unable to load dashboard

The SSO handshake failed.

Solution: This may be due to an improper SSO configuration or using a wrong SSO integration method. If you’re not sure what is wrong, contact GoodData Support.

  • No labels