= Ipsilon Infrastructure SOP

== Contents

[arabic]
. Contact Information
. Description
. Known Issues
. ReStarting
. Configuration
. {blank}
+
Common actions::
  6.1. Registering OpenID Connect Scopes 6.2. Generate an OpenID Connect
  token 6.3. Create OpenID Connect secrets for apps

== Contact Information

Owner::
  Fedora Infrastructure Team
Contact::
  #fedora-admin
Primary upstream contact::
  Patrick Uiterwijk - FAS: puiterwijk
Backup upstream contact::
  Simo Sorce - FAS: simo (irc: simo) Howard Johnson - FAS: merlinthp
  (irc: MerlinTHP) Rob Crittenden - FAS: rcritten (irc: rcrit)
Location::
  Phoenix
Servers::
  ipsilon01.phx2.fedoraproject.org ipsilon02.phx2.fedoraproject.org
  ipsilion01.stg.phx2.fedoraproject.org.
Purpose::
  Ipsilon is our central authentication service that is used to
  authenticate users agains FAS. It is seperate from FAS.

== Description

Ipsilon is our central authentication agent that is used to authenticate
users agains FAS. It is seperate from FAS. The only service that is not
using this currently is the wiki. It is a web service that is presented
via httpd and is load balanced by our standard haproxy setup.

== Known issues

No known issues at this time. There is not currently a logout option for
ipsilon, but it is not considered an issue. If group memberships are
updated in ipsilon the user will need to wait a few minutes for them to
replicate to the all the systems.

== Restarting

To restart the application you simply need to ssh to the servers for the
problematic region and issue an 'service httpd restart'. This should
rarely be required.

== Configuration

Configuration is handled by the ipsilon.yaml playbook in Ansible. This
can also be used to reconfigure application, if that becomes nessecary.

== Common actions

This section describes some common configuration actions.

=== OpenID Connect Scope Registration

As documented on
https://fedoraproject.org/wiki/Infrastructure/Authentication,
application developers can request their own scopes. When a request for
this comes in, look in ansible/roles/ipsilon/files/oidc_scopes/ and copy
an example module. Copy this to a new file, so we have a file per scope
set. Fill in the information:

____
* name is an Ipsilon-internal name. This should not include any spaces
* display_name is the name that is displayed to the category of scopes
to the user
* scopes is a dictionary with the full scope identifier (with namespace)
as keys. The values are dicts with the following keys:
+
____
** display_name: The complete display name for this scope. This is what
the user gets shown to accept/reject
** claims: A list of additional "claims" (pieces of user information) an
application will get when the user
** consents to this scope. For most scopes, this will be the empty list.
____
____

In ansible/roles/ipsilon/tasks/main.yml, add the name of the new file
(without .py) to the with_items of "Copy OpenID Connect scope
registrations"). To enable, open
ansible/roles/ipsilon/templates/configuration.conf, and look for the
lines starting with "openidc enabled extensions". Add the name of the
plugin (in the "name" field of the file) to the environment this
scopeset has been requested for. Run the ansible ipsilon.yml playbook.

=== Generate an OpenID Connect token

There is a handy script in the Ansible project under
`scripts/generate-oidc-token` that can help you generate an OIDC token.
It has a self-explanatory `--help` argument, and it will print out some
SQL that you can run against Ipsilon's database, as well as the token
that you seek.

The `SERVICE_NAME` (the required positional argument) is the name of the
application that wants to use the token to perform actions against
another service.

To generate the scopes, you can visit our link:[authentication] docs and
find the service you want the token to be used for. Each service has a
base namespace (a URL) and one or more scopes for that namespace. To
form a scope for this script, you concatenate the namespace of the
service with the scope you want to grant the service. You can provide
the script the -s flag multiple times if you want to grant more than one
scope to the same token.

As an example, to give Bodhi access to create waivers in WaiverDB, you
can see that the base namespace is
`https://waiverdb.fedoraproject.org/oidc/` and that there is a
`create-waiver` scope. You can run this to generate Ipsilon SQL and a
token with that scope:

....
[bowlofeggs@batcave01 ansible][PROD]$ ./scripts/generate-oidc-token bodhi -e 365 -s https://waiverdb.fedoraproject.org/oidc/create-waiver

Run this SQL against Ipsilon's database:

--------START CUTTING HERE--------
BEGIN;
insert into token values ('2a5f2dff-4e93-4a8d-8482-e62f40dce046','username','bodhi@service');
insert into token values ('2a5f2dff-4e93-4a8d-8482-e62f40dce046','security_check','-ptBqVLId-kUJquqkVyhvR0DbDULIiKp1eqbXqG_dfVK9qACU6WwRBN3-7TRfoOn');
insert into token values ('2a5f2dff-4e93-4a8d-8482-e62f40dce046','client_id','bodhi');
insert into token values ('2a5f2dff-4e93-4a8d-8482-e62f40dce046','expires_at','1557259744');
insert into token values ('2a5f2dff-4e93-4a8d-8482-e62f40dce046','type','Bearer');
insert into token values ('2a5f2dff-4e93-4a8d-8482-e62f40dce046','issued_at','1525723744');
insert into token values ('2a5f2dff-4e93-4a8d-8482-e62f40dce046','scope','["openid", "https://someapp.fedoraproject.org/"]');
COMMIT;
-------- END CUTTING HERE --------


Token: 2a5f2dff-4e93-4a8d-8482-e62f40dce046_-ptBqVLId-kUJquqkVyhvR0DbDULIiKp1eqbXqG_dfVK9qACU6WwRBN3-7TRfoOn
....

Once you have the SQL, you can run it against Ipsilon's database, and
you can provide the token to the application through some secure means
(such as putting into Ansible's secrets and telling the requestor the
Ansible variable they can use to access it.)

=== Create OpenID Connect secrets for apps

Application wanting to use OpenID Connect need to register against our
OpenID Connect server (Ipsilon). Since we do not allow self-registration
(except on iddev.fedorainfracloud.org) for obvious reasons, the secrets
need to be created and configured per application and environment
(production vs staging).

To do so: - Go to the private ansible repository. - Edit the file:
`files/ipsilon/openidc.{{env}}.static` - At the bottom of this file, add
the information concerning the application you are adding. This will
look something like:

____
....
fedocal client_name="fedocal"
fedocal client_secret="<long random string>"
fedocal redirect_uris=["https://calendar.stg.fedoraproject.org/oidc_callback"]
fedocal client_uri="https://calendar.stg.fedoraproject.org/"
fedocal ipsilon_internal={"type":"static","client_id":"fedocal","trusted":true}
fedocal contacts=["admin@fedoraproject.org"]
fedocal client_id=null
fedocal policy_uri="https://fedoraproject.org/wiki/Legal:PrivacyPolicy"
fedocal grant_types="authorization_code"
fedocal response_types="code"
fedocal application_type="web"
fedocal subject_type="pairwise"
fedocal logo_uri=null
fedocal tos_uri=null
fedocal jwks_uri=null
fedocal jwks=null
fedocal sector_identifier_uri=null
fedocal request_uris=[]
fedocal require_auth_time=null
fedocal token_endpoint_auth_method="client_secret_post"
fedocal id_token_signed_response_alg="RS256"
fedocal request_object_signing_alg="none"
fedocal initiate_login_uri=null
fedocal default_max_age=null
fedocal default_acr_values=null
fedocal client_secret_expires_at=0
....
____

In most of situation, only the first 5 lines (up to `ipsilon_internal`)
will change. If the application is not using flask-oidc or is not
maintained by the Fedora Infrastructure the first 11 lines (up to
`application_type`) may change. The remaining lines require a deeper
understanding of OpenID Connect and Ipsilon.

[NOTE]
.Note
====
`client_id` in `ipsilon_internal` must match the begining of the line,
and the `client_id` field must either match the begining of the line or
be `null` as in the example here.
====
[NOTE]
.Note
====
In our OpenID connect server, OIDC.user_getfield('nickname') will return
the FAS username, which we know from FAS is unique. However, not all
OpenID Connect servers enforce this constraint, so the application code
may rely on the `sub` which is the only key that is sure to be unique.
If the application relies on `sub` and wants `sub` to return the FAS
username, then the configuration should be adjusted with:
`subject_type="public"`.
====
After adjusting this file, you will need to make the `client_secret`
available to the application via ansible, for this simply add it to
`vars.yml` as we do for the other private variables and provide the
variable name to the person who requested it.

Finally, commit and push the changes to both files and run the
`ipsilon.yml` playbook.
