Skip to content
Docs BETA

Sign in and get access

For feature teams. This page shows how you sign in to Joomiz and which role you need for each task.

What your platform team gives you

Your platform team gives you:

Joomiz signs people in with OAuth 2.0. You sign in with your identity provider, in the same way as for other tools of your company.

Sign in with joomiz login

Run joomiz login once. The command needs two values, the address of your identity provider and the ID of the client of the CLI. Your platform team gives you both. Give them as options, or set them as variables. Keep offline_access in the scopes, or the CLI cannot renew your sign-in.

Option Variable Meaning
--authority JOOMIZ_AUTHORITY The address of your identity provider.
--client-id JOOMIZ_CLIENT_ID The ID of the client of the CLI.
--scope JOOMIZ_SCOPE The scopes to ask for, separated by spaces.

Run joomiz login --help to see the options in your terminal.

The command works over SSH, because it does not open a browser. It prints a web address and a code:

  1. The line To sign in, open <address> and enter the code: shows the address of your identity provider. A line below it shows the code.
  2. Open the address in a browser on any machine, and enter the code. Enter only a code that your own joomiz login printed.
  3. The CLI prints Waiting for you to finish... until you finish.
  4. The CLI prints Signed in. and the time at which your sign-in expires. It also says whether it can renew the sign-in.

The CLI keeps your sign-in for the next commands. register, validate, plan, apply, runs and audit read it. The CLI renews it before it expires. If renewing fails, the command stops with exit code 2 and names the cause. Run joomiz login again.

Use a token in a pipeline

A pipeline cannot open a browser. It uses a token that your platform team or your pipeline settings give it. A token that a command receives wins over a saved sign-in, and the command starts no sign-in.

Set the token in the variable JOOMIZ_TOKEN. Read it into your shell without showing it:

read -rs JOOMIZ_TOKEN
export JOOMIZ_TOKEN

Paste the token and press Enter. In a pipeline, take the value from the secret store of the pipeline. Do not write a token in a file of your project, and do not type it in a command.

The CLI looks for a credential in this order:

  1. The --token option, then the variable JOOMIZ_TOKEN.
  2. The saved sign-in of joomiz login.

If it finds none, the command stops with exit code 2:

error: no credential is available. Run 'joomiz login', or ... for a non-interactive caller.

The line ... marks words that this page cuts. They name the variable JOOMIZ_TOKEN.

Sign out

There is no sign-out command. To remove your saved sign-in from this computer, delete the file that holds it. It is ~/.joomiz/credentials.json, unless the variable JOOMIZ_CREDENTIALS_FILE names another file. Then run joomiz login to sign in again.

Your role

The role in your sign-in decides what you can do.

Role What it lets you do
owner:<team> Register applications for the team. Check, plan and apply the applications of the team. Read the runs of the applications of the team.
operator The tasks of the platform team, for example releasing an apply lock. This role is for the platform team.

With the role owner:<team> you can act for that team and for no other team. Your platform team tells you which team you are.

When access is refused

A refusal says which part is wrong.

Message Cause Fix
HTTP 401 and Unauthorized The token is not valid, or it has expired. Run joomiz login, or get a new token.
HTTP 403 and Not your application The application belongs to another team. Sign in with the role of the owner team.
HTTP 400 and Invalid owner owner.id in your file is not your team. Write the ID of your own team.
HTTP 403 and Operator role required The command is for the platform team. Ask your platform team.
HTTP 403 and No Joomiz role Your sign-in has no role of Joomiz. The same message appears when you have only the role operator and you run register. Ask your platform team for the role owner:<team>.
HTTP 400 and Ambiguous owner role Your sign-in has the roles of two teams, and register needs one. Sign in with the role of one team.

This is the answer for an application of another team:

error: the control plane could not plan joomiz.yaml (HTTP 403)
  Not your application
  You are not authorized to act on this application. It belongs to a different owner.

A person who holds the roles of two teams cannot register an application. A person who holds only the role operator cannot register one either, because a registration needs exactly one owner:<team> role. Sign in with the role of one team.

Next

Get completion and checks while you write the file in Set up your editor.