[!NOTE] If you are using oauth2-proxy to secure the Swagger UI documentation page, you can log out by visiting the /logout URL. For this to work correctly, ensure that the blueapi server is configured with oidc.logout_redirect_endpoint set to /oauth2/sign_out, which is required for oauth2-proxy.

1.2 Authenticate/Authorise to BlueAPI-Cli#

Authentication#

BlueAPI provides a secure and efficient way to interact with its services. This guide walks you through the steps to log in and log out using BlueAPI with OpenID Connect (OIDC) authentication.

Configuration#

Here is an example configuration for authenticating to p46-blueapi:

api:
  url: "https://p46-blueapi.diamond.ac.uk"

auth_token_path: "~/.cache/blueapi_cache" # Optional: Custom path to store the token

  • auth_token_path: (Optional) Specify where to save the token. If omitted, the default is ~/.cache/blueapi_cache or $XDG_CACHE_HOME/blueapi_cache if XDG_CACHE_HOME is set.

Log In#

  1. Execute the login command:

    $ blueapi -c config.yaml login

  2. Authenticate:

    • Follow the prompts from your OIDC provider to log in.

    • Provide your credentials and complete any additional verification steps required by the provider.

  3. Success Message: Upon successful authentication, you see the following message:

    Logged in and cached new token

Log Out#

To log out and securely remove the cached access token, follow these steps:

  1. Execute the logout command:

    $ blueapi logout

  2. Logout Process:

    • This command uses the OIDC flow to log you out from the OIDC provider.

    • It also deletes the cached token from the specified auth_token_path.

  3. Success Message: If the token is successfully removed or if it does not exist, you see the message:

    Logged out

Authorization#

The authorization provider is opa.diamond.ac.uk

Configuration#

An example configuration to to customise authorization is shown in this config.yaml file.

api:
  url: http://0.0.0.0:8000
env:
  metadata:
    instrument: adsim
  sources:
    - kind: deviceManager
      module: dodal.beamlines.adsim
    - kind: planFunctions
      module: dodal.plans
    - kind: planFunctions
      module: dodal.plan_stubs.wrapped
stomp:
  enabled: true
  url: tcp://localhost:61613/
numtracker:
  url: http://localhost:8406/graphql
tiled:
  enabled: true
  url: http://localhost:8407/api/v1
  authentication:
    client_id: "tiled-writer"
    client_secret: "secret"
oidc:
  issuer: "http://localhost:8081/realms/master"
  client_id: "ixx-cli-blueapi"
  client_audience: "ixx-blueapi"
opa:
  root: "http://localhost:8181/v1/data/diamond/policy/"

Else, the default values in OpaConfig class defined in config.py will be used.