OAuth2.0 UC_OAUTH_SETTINGS

[Joshua Sole]

Hi,

I'm trying to utilize the new OAuth2.0 capabilities over the REST API so Automic users can make REST request with their own users.

I tried to configure the UC_OAUTH_SETTINGS, but the documentation is noc tspecific or does not provide any examples for the values.
i tried it with all varieties of values. Keep in mind, hat in my case <appid> == <clientid>. I don't even know, what an appid is do i just duplicated the aud, which is the <clientid> to the <appid>

JWKS_URL: http://keycloak.example.com:8180/realms/example/protocol/openid-connect/certs -- enpoint has been tested and works, provides a list of jwks
JWT_ID_KEYS: I tried it with 'appid' | 'Application tokens' | 'application ID' | 'aud' while providing an aud and appid field
JWT_SCOPES: 'automic' with the JWT having that scope.

The JWT has a strucute like

{
  ...
  "aud": "<clientid>",
  "appid": "<clientid>",
  "scope": "automic",
  ...
}

For the user, I put in the appropriate OAuth2 Value: '<clientid>' 

Further more, I did the same procedure with 'User tokens' | 'email' and the OAuth2 Value as the usermail from the IdP.

I seems to be able to reach the JWKS endpoint but fails to varify the token. I examined the token send over the REST API to automic from the http request and it is a valid and verifiable token.

It's send via the Authorization Header like 'Authorization: Bearer ey...'. and the response is

{
  "code": 45254,
  "error": "The credentials are not valid.",
  "details": "No detail information available."
}

Thanks in advance and best regards.

EDIT: I also tried it with https and removing JWT_ID_KEYS and JWT_SCOPES and same output

EDIT 2: After loocking into the logs of the REST process, I found this:

20260414/154928.741 - 122    U00045098 Method 'GET', URL: 'https://zzz/ae/api/v1/100/executions', received from IP: '[zzz]' 'User: null/null' 'User-Agent: python-httpx/0.28.1'
20260414/154928.744 - 122    U00045624 JavaScript Object Signing and Encryption failed: Couldn't retrieve JWK set from URL: Connection refused: ey...
20260414/154928.744 - 122    U00045099 The server replied with following status: '401'  

It either mean, the OAuth2.0 JWT verification component in automic is either using the token as the URL, or it's not capable of verifying the token.
Furthermore, the token pasted into the logs (which is bad practice by the way) has its signature cut off, but I can verify, that I'm sending the whole token with the signature.
So it seems like it was shipped broken... The JWKS URL in the UC_OAUTH_SETTINGS and the send token are both fine and can be verified with different tools like python-jose.

[Bogdan Mustiata]

Hi Joshua,

What I would try first is to do the following:
1. Fetch from the host that runs the JWP the JWKS_URL. Maybe some firewall cuts it?
2. Check the following image on how the mapping is being done in the Automation Engine (the JWKS_ALGORITHMS setting was removed from the final implementation, because normally it's anyway controlled from the OAuth2 server)

[Bogdan Mustiata]

And to clarify about the logging, we expected a lot of issues to be caused by the wrong mappings of IDs and/or scopes. This is why we display the token in case of errors with the encryption part cut out, so it's not a valid token. In this case the JOSE library has thrown a connection refused, so my assumption would be that the JWP runs in DMZ and can't access the `http://keycloak.example.com:8180/realms/example/protocol/openid-connect/certs` url.

[Joshua Sole]

Yes there was an issue that the JWKS endpoint was not reachable from the AE server. That has been fixed know.
The previous error is gone but it's still not working
I replicated everything like in the picture.
appid and aud have the same valid client id.
I added in JWT_SCOPES the appid with both versions like the example, seperately and together comma seperated.
The appid is in the OAuth2.0 config of the user.
The JWT token I'm sending is valid and has the approriate claims.

Now I can see in the REST logs:
20260427/092548.019 - 93     U00045098 Method 'GET', URL: 'https://zzz/ae/api/v1/100/executions', received from IP: 'zzz' 'User: null/null' 'User-Agent: python-httpx/0.28.1'
20260427/092548.023 - 93     U00045621 No scope was allowed in UC_OAUTH_SETTINGS.JWT_SCOPES for token ey...<token_without_pub_sig>
20260427/092548.024 - 93     U00045099 The server replied with following status: '401'  

JWT_SCOPES : <clien_id_like_appid_and_aud>
Could it be that the request has User null/null? Do I need to change the http request headers?
Why is it saying no scope was allowed? It's in the UC_OAUTH_SETTINGS and in the JWT?

Should I rather start a discussion with that topic?

[Bogdan Mustiata]

Hi Joshua,

The error you're getting seems to indicate the `aud` (audience) value from the token's payload is not set in the `JWT_SCOPES` key of the VARA. This is how we can identify that the token we're receiving is actually targeted for Automic Automation, and not another application. You could base64 decode the payload - the 2nd field after the . and see what actual value you're receiving.

[Joshua Sole]

The JWT in the REST log shows

{
  ...
  "aud": "webapp",
  "appid": "webapp",
...
}

And the "UC_OAUTH_SETTINGS" have
"JWT_SCOPES" : "webapp"

And the error log:

20260427/092633.767 - 111    U00045098 Method 'GET', URL: 'https://zzz/ae/api/v1/100/executions', received from IP: 'zzz' 'User: null/null' 'User-Agent: python-httpx/0.28.1'
20260427/092633.772 - 111    U00045621 No scope was allowed in UC_OAUTH_SETTINGS.JWT_SCOPES for token ey...
20260427/092633.782 - 111    U00045099 The server replied with following status: '401'  

I don't see any error here regarding the provided information.
Is it client dependent? So I need to specify a user somehow in the http headers?

[Joshua Sole]

I noticed that I had a UC_OAUTH_SETTINGS on the target client 100 as well and it was interfering with the one I was testing with on client 0. I can confirm, that the appid rout is working.

But one more question if I may ask:
If I just ask for an appid, it will probably be only mapped to one automic user per client. That would give us a OAuth way to make service accounts.
But if I want to allow certain users OAuth access, then I define an email claim as far as I understand.
The mail goes into the OAuth field for each user?
Is it possible to combine appid and email claims?
appid claim to limit the access of users and email claim to identify whos making the call?
If you could answer that I would be very thankful

[Bogdan Mustiata]

Hi Joshua,

Yes, you are 100% correct. They can be combined. The `JWT_ID_KEYS` is actually a CSV and its entries are searched in order. The default for it is actually `email,appid` for this exact reason.

The first value that matches the token claims is used to search the users table. This value is used to find the matching Automation Engine user with the same OAuth Value as is defined in the token received from OAuth2.

If no match is possible, the user gets a 401.

ID tokens (tokens that identify an user) would have `email`, or in some cases `oid` (object ID), and client tokens (tokens that identify another application, i.e. service accounts) would use `appid`.

That's why we allow customizing the value, but go with reasonable defaults.

[Joshua Sole]

Thanks that's incredibly helpful information.
I think this Thread will be helpful to a lot of people looking into OAuth/OIDC

There is one last question to round everythin up.
I believe then the JWT_ID_KEYS is the header of the csv and JWT_SCOPES would be the data?
If I want to enable multiple user over mutliple apps, how would I need to add those to the JWT_SCOPES?

client_1 ',' user_mail_1 '\n' client_2 ',' user_mail_2 '\n'

Something like that? Or what would the syntax be?

Btw this thread should be recommmended for the people who are doing the documentation.

[Bogdan Mustiata]

Hi Joshua,

No, that's not correct. Let me break down what happens when we receive a token.
1. We check if this token is addressed to us. This happens if we have a `JWT_SCOPES` setting; we'll check if the `aud` value from the token matches what we have. (Just FYI: We'll deprecate this setting name, and change it to `JWT_AUDIENCES`, since scopes mean a different thing in OAuth2 terminology. Scopes mean basically the role the user would have in an application. The audience would be the actual application.).
2. We look at the cryptographic signature of the token. We match it with the public keys we have from the `JWKS_URL`.
If 1 and 2 passed, we know we have a legitimate token from the authority, be it either a service account (client/application in OAuth2 terminology) or a regular user. It's time now to match it to an AE user. If any of them fail -> 401.
3. We look in the received token for the first non-empty value from the `JWT_ID_KEYS`. We basically take first `email`, then `appid`, etc. and try to get the value. No value matches? -> 401.
4. We look for the value we found to match it with a user in the AE system. This is the value you see in the User view in the `OAuth2 Value`. That's how we cross-reference the user, and allow you to have any extra properties on the token, to map it to AE users.

I hope that clarifies it.

[Bogdan Mustiata]

Hi Joshua,

My statement that the setting is a CSV: "The `JWT_ID_KEYS` is actually a CSV and its entries are searched in order." Is just means the value in the VARA can be:

| Name        | Value       |
| JWT_ID_KEYS | email,appid |
| JWKS_URL    | http://...  |