API roles and localization

Internal users and user role queries

When an internal user makes an API call, BillingCenter queries the database for the user's user roles. This query returns the user roles using the BillingCenter default application language, as specified by the DefaultApplicationLanguage parameter in config.xml. These results are then compared to the names of the API roles. Whenever there is a match, the internal user is given the access specified in the API role.

Therefore, if you change the DefaultApplicationLanguage parameter, the names of the user roles returned by the query will be in the new language. To ensure that internal users are granted the correct access, you must also change the names of the API role files used by internal users. Guidewire also recommends changing the name of the role within the file itself.

For example, suppose there is a user role in BillingCenter named "Auditor". This user role maps to an API role named "Auditor.role.yaml". The BillingCenter 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, the API role file's name must be changed to "Auditeur.role.yaml".

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 BillingCenter 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 BillingCenter.

For example, suppose you wanted to create an external user role for accountants, and you wanted to do this using French. In BillingCenter, 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.