Access to your Sauron endpoints

Use this page to choose the right authentication method for browser users, automation, and client workflows.

Access method Use it for
Oracle SSO Human browser access to Sauron UI endpoints.
OAuth 2.0 Bearer token Sauron API automation and supported SSO-enabled non-Grafana automation.
Basic Authentication Client workflows where the endpoint supports username and password access, such as log shippers or PushProx.
Grafana service account token Grafana API automation.
Which access method should I use?
  • Use Oracle SSO when you are a human user opening Sauron UI endpoints such as Grafana, OpenSearch Dashboards, Prometheus, Thanos, Alertmanager, API, Help, or Console in a browser.
  • Use OAuth 2.0 Bearer token access for Sauron API automation and other SSO-enabled non-Grafana endpoint automation.
  • Use Basic Authentication or Bearer token access for client workflows, such as Fluentd or other log shippers sending data to OpenSearch, or a PushProx client registering scrape targets. Use the method supported and approved for that endpoint and client.
  • Use a Grafana service account token for Grafana endpoint automation. Grafana API keys also work, but they are deprecated in Grafana 9.1+.

If you are not sure which access method applies, ask your Sauron owner which endpoint and role you need before requesting credentials or OIM access.

Auth and client quick reference
Use case Recommended access method Notes
Human user opening Grafana, OpenSearch Dashboards, Prometheus, Thanos, Alertmanager, API, Help, or Console in a browser Oracle SSO Request the correct OIM entitlement for the role and endpoint you need.
Grafana API automation Grafana service account token Grafana API keys also work, but they are deprecated in Grafana 9.1+.
OpenSearch log clients such as Fluentd, FluentBit, or other log shippers Basic Authentication or approved Bearer token path Reporter credentials are limited to reporter-safe service endpoints such as OpenSearch, Prometheus/Prometheus Gateway, PushProx, Shuttleproxy, and Thanos gRPC.
PushProx client Basic Authentication or OAuth 2.0 Bearer token OAuth 2.0 Bearer token access requires SSO to be enabled for the PushProx endpoint.
Sauron API automation OAuth 2.0 Bearer token Generate an admin-role Bearer token with PUT /v1/oauth2/token. The token API can be accessed only by Basic Auth admin users or users in the Admin OIM entitlement.
Oracle SSO

You can enable SSO for your Sauron endpoints based on instructions here

Basic Authentication

Sauron supports 3 types of users with Basic Authentication access.

  • Admin user - This is user created by default for your Sauron. Credentials for this user is in email you received after Sauron was provisioned by us.
  • Secondary Admin user - You can optionally create a Secondary Admin user for your Sauron. Steps to create Secondary Admin user are here.
  • Reporter user - This is another user created by default for your Sauron. Credentials for this user is in email you received after Sauron was provisioned by us. If there is no reporter user created for your Sauron (specifically for old Saurons), you can create one. This user can be used by your clients (e.g. Filebeat, Journalbeat, Metricbeat, PushProx, or Shuttleproxy) to send logs or metrics to your Sauron, so you don't have to use your Admin credentials. Reporter credentials are limited to reporter-safe service endpoints such as OpenSearch, Prometheus/Prometheus Gateway, PushProx, Shuttleproxy, and Thanos gRPC. Steps to create Reporter user are here.
Basic Auth and Bearer Token Endpoint Matrix

This matrix summarizes auth-sidecar endpoint access for local admin, secondary admin, and reporter credentials. Oracle SSO roles are described in the Oracle SSO and OIM sections. Grafana Editor is Grafana-only.

Credential type Grafana Prometheus / Prometheus Gateway Alertmanager Thanos UI Thanos gRPC API Help Console OpenSearch PushProx Shuttleproxy
Admin x x x x x x x x x x x
Secondary Admin x x x x x x x x x x x
Reporter x x x x x
Steps to create Secondary Admin User
  • Go to PUT /v1/user/create API, click Try it Out and make sure secondary selected in dropdown.
  • Enter your password in password and confirmPassword fields and click Execute
  • Your Secondary Admin User is now created. You can use it to access any Sauron endpoint with admin access.
  • Username for Secondary Admin user is [Admin username] + [2]. e.g. if Admin username is test, Secondary Admin username will be test2
Steps to create Reporter User
  • Go to PUT /v1/user/create API, click Try it Out and make sure reporter selected in dropdown.
  • Enter your password in password and confirmPassword fields and click Execute
  • Your Reporter User is now created. You can use it to configure your logs or metrics client.
  • Username for Reporter user is [Admin username] + [-reporter]. e.g. if Admin username is test, Reporter username will be test-reporter
Steps to reset password
  • Go to PUT /v1/user/password API, click Try it Out.
  • Enter userName, oldPassword, newPassword and confirmNewPassword and click Execute
  • Your password is now reset. Give 1-2 minutes for the process to complete.

Access with above users will continue even after enabling SSO for your Sauron endpoints. To enable SSO follow steps here.

OAuth 2.0 Bearer token
Grafana endpoint

Sauron supports both service account tokens (Grafana 9.1+) and API keys (deprecated) to access your Sauron Grafana API endpoints.

Service account token:

Once you generate your service account token using Grafana UI, you can use this token to access your Grafana endpoint. e.g.

GRAFANA_SERVICE_ACCOUNT_TOKEN='replace-with-your-grafana-service-account-token'
curl -H "Authorization: Bearer ${GRAFANA_SERVICE_ACCOUNT_TOKEN}" \
  'https://grafana.stage.apatil.developers.oracledx.com'
API key (deprecated in Grafana 9.1+):

Once you generate Grafana API key, use it to access your Grafana endpoint. (Note: API keys are deprecated. Grafana recommends using service account tokens) e.g.

GRAFANA_API_KEY='replace-with-your-grafana-api-key'
curl -H "Authorization: Bearer ${GRAFANA_API_KEY}" \
  'https://grafana.stage.apatil.developers.oracledx.com'
Non-Grafana endpoints

Sauron supports OAuth 2.0 Bearer token access to your SSO enabled non-Grafana endpoints. Use Bearer tokens for Sauron API automation.

You can create a bearer token with one of the following roles:

  • admin (has full access to all endpoints)
  • reporter (has access to reporter-safe service endpoints such as OpenSearch, Prometheus/Prometheus Gateway, PushProx, Shuttleproxy, and Thanos gRPC)

You can create maximum 2 tokens for each role so that you can rotate them on client side without any down time:

  • admin1, admin2 tokens for admin role
  • reporter1, reporter2 tokens for reporter role

Use PUT /v1/oauth2/token API to generate a new OAuth 2.0 Bearer token for admin or reporter roles.

Once you generate a token, you can access your endpoint as shown below:

SAURON_BEARER_TOKEN='replace-with-generated-sauron-bearer-token'
SAURON_BEARER_TOKEN_B64="$(printf '%s' "${SAURON_BEARER_TOKEN}" | base64 | tr '+/' '-_' | tr -d '\n')"

curl -o /dev/null -s -w '%{http_code}\n' \
  -H "Authorization: Bearer ${SAURON_BEARER_TOKEN_B64}" \
  'https://api.stage.apatil.developers.oracledx.com'

Note:

  • You need to enable SSO for your endpoints in order to support this feature. Steps to enable SSO are here

  • PUT /v1/oauth2/token API can be accessed only by basic-auth admin users or users that belong to [Team]Admin OIM entitlements. All other users will receive 403 Access Denied

  • Generating a new Bearer token using this API invalidates previous token for that role. e.g. if you generate new token for admin1, previous admin1 token is no longer valid. If you use old admin1 token to access your endpoint, you will receive 403 Access Denied.

Self-check before escalation

Most questions for this topic can be resolved with the steps above. For access issues, check and collect:

  • Sauron URL.
  • Endpoint that failed.
  • Authentication method: SSO, Basic Authentication, or Bearer token.
  • Expected role or user type.
  • Exact error/status or screenshot.
  • Start time.
  • Recent access, credential, token, or entitlement changes.
  • Checks completed.
  • Production impact, if any.
  • Whether another endpoint for the same Sauron works.
  • Whether the same access worked before and when it changed.

Do not paste passwords, bearer tokens, private keys, or reset links in Slack.