Skip to content

Command line tools

We provide some command line tools in order to get a valid SSO session token without using a web browser.

Warning

We generally don't recommend Kerberos or cookie-based tools to secure or call web APIs. The only supported cases are migrations from cern-get-sso-cookie to auth-get-sso-cookie, and this support will stop in the long term. We will request API owners to stop accepting cookies and migrate them to better alternatives, such as JWT tokens from the CERN SSO. API clients will be able to get credentials using API Access tokens.

Overview

Tool Input credentials Output credentials 2FA supported Works for interactive sessions
(user in front of a computer)		 Works for automated flows
(e.g. acronjobs)
auth-get-sso-cookie ⚠️ Kerberos ticket ⚠️ SSO cookies 🚫 no ✅ yes ✅ yes
auth-get-sso-token ⚠️ Kerberos ticket OIDC token 🚫 no ✅ yes ✅ yes
auth-get-user-token browser-based SSO login with any usual credentials (password, Kerberos, 2FA) OIDC token ✅ yes ✅ yes 🚫 no
oidc-agent* different SSO login flows supported, with locally managed refresh tokens for persistent sessions OIDC token ✅ yes ✅ yes ✅ yes

(*) This tool is not part of the CERN package, but it is also available on LXPLUS.

Installing the package

These command line tools are already installed on lxplus.cern.ch clusters.

If you want to install them on other machines, the RPM packages are available in the authz[OS]-stable internal repository (Koji tag) - for example:

After adding the RPM source, you will be able to install the package:

yum install auth-get-sso-cookie

This utility is a replacement for cern-get-sso-cookie for the new SSO.

auth-get-sso-cookie acquires CERN Single Sign-On cookie using Kerberos credentials allowing for automated access to CERN SSO protected pages using tools alike wget, curl or similar.

2FA authentication is currently not supported.

Usage

You will need a valid Kerberos TGT to run the utility: run kinit <user> before the script.

Use this tool to get a valid SSO and application cookie from a protected URL. This cookie will be valid for 10 hours.

Warning

Every time you get new cookies, this will start a new SSO session but it won't log off any other session. To avoid starting too many sessions, please reuse your cookies as much as possible while they are valid.

$ auth-get-sso-cookie --help
usage: auth-get-sso-cookie [-h] [-u URL] [-o OUTFILE] [--nocertverify]
                        [--verbose] [--debug] [--auth-server AUTH_SERVER]

Acquires the CERN Single Sign-On cookie using Kerberos credentials.
(Note that 2FA authentication is currently not supported.)

optional arguments:
  -h, --help            show this help message and exit
  -u URL, --url URL     CERN SSO protected site URL to get cookie for.
  -o OUTFILE, --outfile OUTFILE
                        File to store the cookie for further usage
  --nocertverify        Disables peer certificate verification. Useful for
                        debugging/tests when peer host does have a self-signed
                        certificate for example.
  --verbose, -v         Provide more information on authentication process
  --debug, -vv          Provide detailed debugging information
  --auth-server AUTH_SERVER, -s AUTH_SERVER
                        Authentication server (default: auth.cern.ch)

auth-get-sso-cookie -u <url> -o <cookies_file>

Example:

auth-get-sso-cookie -u https://openstack.cern.ch -o cookies.txt
curl -L -b cookies.txt https://openstack.cern.ch

It is possible to migrate from cern-get-sso-cookie to auth-get-sso-cookie and make your integrations compatible with the old and the new SSO at the same time using Kerberos credentials (this compatibility will be limited to a transition period until the old SSO is decommissioned). Certificate credentials are not supported by the new tool, neither in the old SSO.

Steps to migrate to the new tool:

  1. Install the RPM package: yum install auth-get-sso-cookie

  2. Replace all your calls to cern-get-sso-cookie with auth-get-sso-cookie, or create a symlink as described below.

If you have too many calls to replace in your code or you prefer not to change it, it can be easier to uninstall cern-get-sso-cookie and add a symbolic link to auth-get-sso-cookie.

  1. yum remove cern-get-sso-cookie
  2. ln -s /usr/bin/auth-get-sso-cookie /usr/bin/cern-get-sso-cookie

auth-get-sso-token

This is a legacy tool and it will be removed in the future. It is NOT compatible with accounts that have "always-on 2FA". Please use one of the following available alternatives:

  • When getting access tokens for a user (interactive workflows): auth-get-user-token.
  • For automated workflows: OAuth2 Client Credentials Grant or the API-Access endpoint.

Use this tool to get a valid SSO token for a protected URL. The obtained token will be valid for 20 minutes.

Info

The scope of this tool is to have an easy way for debugging/testing authentication for APIs and web applications from the command line. It can also work for securing APIs as an alternative to cern-get-sso-cookie, but it is not supported for production services. We recommend using API Access for most integrations.

$ auth-get-sso-token --help
usage: auth-get-sso-token [-h] [--url URL] [--clientid CLIENTID] [--nocertverify] [--verbose] [--debug]

Acquires a user token for a public client using Kerberos credentials

optional arguments:
  -h, --help            show this help message and exit
  --url URL, -u URL     Application or Redirect URL. Required for the OAuth request.
  --clientid CLIENTID, -c CLIENTID
                        Client ID of a public client
  --nocertverify        Disables peer certificate verification. Useful for debugging/tests when peer host does have a self-signed certificate for example.
  --verbose, -v         Provide more information on authentication process
  --debug, -vv          Provide detailed debugging information

Example:

TOKEN=$(./auth-get-sso-token -u http://localhost:5000 -c public-client)
curl -X PUT "https://localhost:5000/api/foobar" -H  "authorization: Bearer $TOKEN" -d "{\"foo\": \"bar\"}"

auth-get-user-token

Use this tool to get a valid SSO token for a client that accepts Device Authorization Grant. The obtained token will be valid for 20 minutes.

Info

For confidential clients (OIDC SSO registrations that have a clientId and a secret), you need to use the parameter AUDIENCE.

Example:

auth-get-user-token -c my-public-client -o token.txt -x
token=$(<token.txt)
curl -X PUT "https://myapi.cern.ch/api/foobar" -H  "authorization: Bearer $token" -d "{\"foo\": \"bar\"}"

In case the client is confidential:

  1. create a second application in the application portal, for example my-new-public-client
  2. allow token exchange between my-new-public-client and the existing confidential client on the SSO registration tab of my-new-public-client in the application portal
  3. run: auth-get-user-token -c my-new-public-client -a my-confidential-client -o token.txt -x, where -a is the audience: Exchange token for another target client ID

For more details, please see our Gitlab repository.