SSO 5.00 upgrade guide

These topics describe product changes you must be aware of when upgrading to version 5.00.

Important:

This is an incremental upgrade guide that covers only topics related to the Single sign-on version specified in the page title. Check prior upgrade guides if you migrate from an earlier version, and complete the migration tasks for all versions between your existing version and the target version in order. Make sure to also read about the new features for this version.

Corresponding new features page: SSO 5.00 new features.

Previous upgrade guide: SSO 4.01 upgrade guide.

Authorization scopes are renamed Authorization roles

Starting from GIP 5.00, authorization scopes are renamed Authorization roles. Where before in Genero Identity Provider (GIP) there were two different scopes: Authorization scopes and Access scopes, now these are labelled as:
  • Authorization roles (for example, Role.User, and so on)
  • Access scopes (for example, OpenID, profile, and so on)

There is no change to how you use these scopes, just the label is renamed for authorization roles. Internally, the GIP now provides the authorization roles in the ID token instead of the access token.

Access scopes remain as they were; the label has not changed, and the GIP provides them in the access token.

You will notice that the Console App screens for configuring permissions have enhancements to the UI for this feature.
Figure: ConsoleApp group permissions

Images shows ConsoleApp screen for configuring group permissions

For more information on authorization roles and access scopes, go to Manage authorization roles and Manage web service access scopes.

New method GetIdRoles() for retrieving authorization roles

Starting from FGLGWS 5.00, the OAUTH API has a new method called OAuthAPI.GetIdRoles() to explicitly retrieve authorization roles.

Where previously you used OAuthAPI.GetIdScopes() to retrieve both the list of scopes and roles from an ID or access token provided by an Identity provider using OAuth2 Single sign-on, you now need to use the dedicated method to retrieve roles.

For details, refer to the GetIDRoles page in Genero Business Development Language User Guide.

OpenIDConnect service supports OIDC_ROLES

Starting from FGLGWS 5.00, the Genero OpenIDConnect service now decodes ID tokens containing roles instead of scopes, and creates a new environment variable called OIDC_ROLES containing the list of roles.

Where previously you used OIDC_SCOPES to retrieve both the list of scopes and roles from an ID or access token provided by an Identity provider using OpenID Connect/OAuth2 Single sign-on, you now need to use the dedicated variable to retrieve roles.

For an example using OIDC_ROLES, see Retrieve roles and scopes.

Changes to the OpenIDConnect service configuration

Starting from FGLGWS 5.00.02, 4.01.07, and 3.21.02, two parameters of the Genero OpenIDConnect service configuration ($FGLDIR\web_utilities\services\openid-connect\res\configuration) have changes:

  • The oidc.logout.id_token_hint parameter, used in the logout request sent to the provider, has been replaced by oidc.logout.identifier. The new parameter supports the values "id_token_hint", "client_id", or an empty (" ") value. The default value is "id_token_hint".
  • The oidc.logout.post_redirect parameter, used to send the post redirect uri in the logout request, now needs a string value instead of the boolean value true/false on previous versions. The default value is now "post_logout_redirect_uri".

No action needs to be taken on your part, but if you have previously used a custom OpenIDConnect configuration file and you want to use it when upgrading FGLGWS version, ensure that you review your configuration for these parameters.

For more information on OpenID Connect Single sign-on, go to OpenID Connect/OAuth2 SSO.

The GeneroAccessService supports scopes set in configuration file

Starting from FGLGWS 5.00.02 and GIP 5.00.02, the GeneroAccessService service can now secure a web service from scopes set in the web service configuration file (xcf).

No action needs to be taken on your part, but if you want to secure legacy REST web services that do not define any WSScope attributes or that are written with the REST low-level API, then you can secure them by configuring the SCOPE element in the configuration file. The GeneroAccessService will verify if the access token provided by the client application has all the necessary scopes specified in the SCOPE element.

For more information about configuring scopes, refer to the SCOPE (for service) topic in the Genero Application Server User Guide.

Using an identity provider's registration endpoint

Starting from FGLGWS 5.00.03, there are updates to how you manage and use the registration endpoint of an identity provider using the OpenID Connect/OAuth2 Single sign-on protocol.

If you have an application that is protected by an identity provider via OpenIDConnectServiceProvider and a registration endpoint has been set:
  • You can view the identity provider's registration endpoint using the ImportOAuth tool's --show option.
  • At runtime, an environment variable called OIDC_REGISTRATION_ENDPOINT will be available, and you can load it in your Genero application via fgl_getenv("OIDC_REGISTRATION_ENDPOINT"). For example, you might want to register or unregister an application with the identity provider. A valid access token is required to perform this procedure.

For more information about managing registration endpoints, go to ImportOAuth, Show IdP metadata, and Retrieve registration endpoint.

Changes in earlier versions

Make sure to check the upgrade notes of earlier versions, to not miss changes introduced in maintenance releases. For more details, see SSO 4.01 upgrade guide.