API roles and localization

Internal users and user role queries

When an internal user makes an API call, PolicyCenter queries the database for the user's user roles. Cloud API match a user role to an API role if either (1) the API role has the exact same name as the user role, or (2) the user role has been translated into a non-English language and there is an API role matching one of the translations. Whenever there is a match, the internal user is given the access specified in the API role.

Therefore, if you change the application's default language, to ensure that internal users are granted the correct access, you must also do one of the following:

1. Change the names of any API role files used by internal users. (Guidewire also recommends changing the name of the role within the file itself.) OR
2. Ensure that, for every API role used by internal users, there is a non-English translation for the role name.

For example, suppose there is a user role in PolicyCenter named "Auditor". This user role maps to an API role named "Auditor.role.yaml". The PolicyCenter default language is changed to French. As a result of this change, the query now returns the role name as "Auditeur". To ensure that access to this role is granted appropriately, either the API role file's name must be changed to "Auditeur.role.yaml", or there must be a translation from "Auditor" to "Auditeur".

External users and IdP roles

For external users, the roles associated with each user are stored in either the IdP (and the information is submitted using the JWT) or an additional authorization application (and the information is retrieved by the IExpandTokenPlugin plugin). Regardless of where the roles comes from, each role is prefixed with a "cc.", "pc.", or "bc.". When PolicyCenter receives the call, it converts the JWT to a token map and calls the IExpandTokenPlugin plugin to modify or add tokens based on information from any relevant additional authorization application. Then, it looks for any role names in the token map prefixed with a "cc.", "pc.", or "bc.". It strips off the prefix and then compares the remaining name with the names of the API roles. Whenever there is a match, the external user is given the access specified in the API role.

You can use any language for external roles, even if it is not the default language. But you must ensure that role names match between the IdP/additional authorization application and PolicyCenter.

For example, suppose you wanted to create an external user role for accountants, and you wanted to do this using French. In PolicyCenter, the role could be named "comptable.role.yaml". If roles are stored in the IdP, the IdP would need to assert the appropriate users are associated with "cc.comptable", "pc.comptable", or "bc.compatable". If roles are stored in an additional authorization application, this application would need to respond to the IExpandTokenPlugin plugin's request with "cc.comptable", "pc.comptable", or "bc.compatable".

The prefix for external roles must always be "cc.", "pc.", or "bc.", even if the remainder of the role name uses a different character set, such as Japanese Kanji.

API roles for specific caller types

There are several roles that are designed for specific types of callers:

These roles are referenced by internal code or used by other Guidewire services and applications.