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 the IdP. When an external user makes a Cloud API call, their associated roles are first stored inside a JWT. Each role is prefixed with a "cc.", "pc.", or "bc.". When BillingCenter receives the call, it looks for any role names in the JWT 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 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". The IdP would need to assert the appropriate users are associated 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. Do not change the names for these role files, regardless of the language you are working in. Doing so will cause Cloud API authorization to not work properly.