For a SFDC connected app (and potentially elsewhere), you can use a 3rd-party JSON Web Token for user authentication. Similarly to SAML, there is no need for hard coded per-user credentials, instead a system-to-system trust relation is established using signed tokens.
The configuration is stored in a per-partition configuration in an advanced configuration option with the name externalJWTConfiguration.
Its structure is in the JSON format with the following details:
{
entries : {
<externalSystemName> : {
publicKey : <public key used by external system for signing in PEM format>
permissions: <null or JSON list of Strings with permissions names>
}
}
} |
Where:
externalSystemName is a JSON compatible name of the external system (i.e., only [A-Za-z0-9], no whitespaces, etc). This name is also used in the bearer auth header (see below). You can add as many external systems as you like, each with an individual name.
publicKey is a string representation of the public key in the PEM format (see below for an example). We only support RSA keys.
permissions can be null (or omitted) – in that case the trust does not further restrict permissions (= allow all). If there is a list defined, then any API call using that token/config will only be allowed if the endpoint’s permission requirement matches the permissions listed here.
Important: This list is just an additional filter. I.e., the authenticated user as such needs to have the required permission to begin with. This setting will not add or allow anything the user could do using regular authentication. It can be used to restrict the trust relation to specific API calls only.
Example of a public key:
-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0E9Zp0JNbDaOMqhZd1C+ /FdBTCjza0qXcjTYCbDUeY89qPpwN19QovmehCVGBSFzLOkltx0YmlCkaKLtzqfS ... ... (edited for security reasons) ... fXr4+6SBmEOVa7RSzoXr3whpdMdKsIvnDCCmT++aJvHBw63ZKGKb8+ZTAXv0z3sm LDRyhifUmEoJPGWHV6/oxZQiVRapEFe7SiVTbr2IW7OfrdE3DVrioJmATEKgVr5i zwIDAQAB -----END PUBLIC KEY----- |
Once the trust relationship is configured, you can use it to authenticate API calls. This is done by sending the signed (by the external system possessing the private key part) and compacted JWT token returned by the server in the standard Authorization HTTP header in the following form:
Authorization: BEARER <externalSystemName>;<signed JWT token> |
The JWT token follows standard RFC rules in terms of structure, signature, etc. Please note that only RS256 signature method is supported.
The content of the token consists of three parts with a certain structure:
Header:
{
"alg": "RS256"
} |
alg identifies the algorithm used to generate the signature. It must always be set to RS256 – other algorithms are not supported.
Payload:
{
"sub": "root",
"iss": "AllowAll",
"aud": "integration-test",
"partition": "system"
} |
sub is the standard subject field of the JWT token. It must contain the loginName of the user.
iss is the standard issuer field of the JWT token. It must contain the external system name value (i.e., the same name as in the trust config and in the HTTP header).
aud is the standard audience field of the JWT token. It must contain the Pricefx cluster name.
partition must be set to the partition of the target & user.
Signature
The signature part is a combination of the encoded header, the encoded payload, a secret, the algorithm specified in the header – all that signed.