<commit_before>[[admin-guide-service-accounts]]
= Configuring Service Accounts
{product-author}
{product-version}
:data-uri:
:icons:
:experimental:
:toc: macro
:toc-title:

toc::[]

ifdef::openshift-dedicated[]
include::admin_guide/osd_request.adoc[]
endif::[]

== Overview

ifdef::openshift-origin,openshift-enterprise,openshift-dedicated[]
When a person uses the {product-title} CLI or web console, their API token
authenticates them to the {product-title} API. However, when a regular user's
credentials are not available, it is common for components to make API calls
independently. For example:

* Replication controllers make API calls to create or delete pods.
* Applications inside containers can make API calls for discovery purposes.
* External applications can make API calls for monitoring or integration purposes.

endif::[]
Service accounts provide a flexible way to control API access without sharing a
regular user's credentials.

[[sa-user-names-and-groups]]
== User Names and Groups

Every service account has an associated user name that can be granted roles,
just like a regular user. The user name is derived from its project and name:

----
system:serviceaccount:<project>:<name>
----

For example, to add the *view* role to the *robot* service account in the
*top-secret* project:

====
----
$ oc policy add-role-to-user view system:serviceaccount:top-secret:robot
----
====

Every service account is also a member of two groups:

system:serviceaccounts:: Includes all service accounts in the system.
system:serviceaccounts:<project>:: Includes all service accounts in the
specified project.

For example, to allow all service accounts in all projects to view resources in
the *top-secret* project:

====
----
$ oc policy add-role-to-group view system:serviceaccounts -n top-secret
----
====

To allow all service accounts in the *managers* project to edit resources in the
*top-secret* project:

====
----
$ oc policy add-role-to-group edit system:serviceaccounts:managers -n top-secret
----
====

[[enabling-service-account-authentication]]
== Enabling Service Account Authentication

Service accounts authenticate to the API using tokens signed by a private RSA
key. The authentication layer verifies the signature using a matching public RSA
key.

To enable service account token generation, update the `*serviceAccountConfig*`
stanza in the *_/etc/origin/master/master-config.yml_* file on the master to
specify a `*privateKeyFile*` (for signing), and a matching public key file in
the `*publicKeyFiles*` list:

====
----
serviceAccountConfig:
  ...
  masterCA: ca.crt <1>
  privateKeyFile: serviceaccounts.private.key <2>
  publicKeyFiles:
  - serviceaccounts.public.key <3>
  - ...
----
<1> CA file used to validate the API server's serving certificate.
<2> Private RSA key file (for token signing).
<3> Public RSA key files (for token verification). If private key files are
provided, then the public key component is used. Multiple public key files can
be specified, and a token will be accepted if it can be validated by one of the
public keys. This allows rotation of the signing key, while still accepting
tokens generated by the previous signer.
====

[[managed-service-accounts]]
== Managed Service Accounts

Service accounts are required in each project to run builds, deployments, and
other pods. The `*managedNames*` setting in the
*_/etc/origin/master/master-config.yml_* file on the master controls which
service accounts are automatically created in every project:

====
----
serviceAccountConfig:
  ...
  managedNames: <1>
  - builder <2>
  - deployer <3>
  - default <4>
  - ...
----
<1> List of service accounts to automatically create in every project.
<2> A *builder* service account in each project is required by build pods, and is
given the *system:image-builder* role, which allows pushing images to any image
stream in the project using the internal container registry.
<3> A *deployer* service account in each project is required by deployment pods, and
is given the *system:deployer* role, which allows viewing and modifying
replication controllers and pods in the project.
<4> A *default* service account is used by all other pods unless they specify a
different service account.
====

All service accounts in a project are given the *system:image-puller* role,
which allows pulling images from any image stream in the project using the
internal container registry.

[[infrastructure-service-accounts]]
== Infrastructure Service Accounts

Several infrastructure controllers run using service account credentials. The
following service accounts are created in the {product-title} infrastructure
project (*openshift-infra*) at server start, and given the following roles
cluster-wide:

[cols="1,3",options="header"]
|====
|Service Account |Description

|*replication-controller*
|Assigned the *system:replication-controller* role

|*deployment-controller*
|Assigned the *system:deployment-controller* role

|*build-controller*
|Assigned the *system:build-controller* role. Additionally, the
*build-controller* service account is included in the privileged
xref:manage_scc.adoc#admin-guide-manage-scc[security context constraint] in order to create privileged
build pods.
|====

To configure the project where those service accounts are created, set the
`*openshiftInfrastructureNamespace*` field in in the
*_/etc/origin/master/master-config.yml_* file on the master:

====
----
policyConfig:
  ...
  openshiftInfrastructureNamespace: openshift-infra
----
====

Set the `*limitSecretReferences*` field in the
*_/etc/origin/master/master-config.yml_* file on the master to `true` to require
pod secret references to be whitelisted by their service accounts. Set its value
to `false` to allow pods to reference any secret in the project.

====
----
serviceAccountConfig:
  ...
  limitSecretReferences: false
----
====<commit_msg>heading for service account/secret section<commit_after>[[admin-guide-service-accounts]]
= Configuring Service Accounts
{product-author}
{product-version}
:data-uri:
:icons:
:experimental:
:toc: macro
:toc-title:

toc::[]

ifdef::openshift-dedicated[]
include::admin_guide/osd_request.adoc[]
endif::[]

== Overview

ifdef::openshift-origin,openshift-enterprise,openshift-dedicated[]
When a person uses the {product-title} CLI or web console, their API token
authenticates them to the {product-title} API. However, when a regular user's
credentials are not available, it is common for components to make API calls
independently. For example:

* Replication controllers make API calls to create or delete pods.
* Applications inside containers can make API calls for discovery purposes.
* External applications can make API calls for monitoring or integration purposes.

endif::[]
Service accounts provide a flexible way to control API access without sharing a
regular user's credentials.

[[sa-user-names-and-groups]]
== User Names and Groups

Every service account has an associated user name that can be granted roles,
just like a regular user. The user name is derived from its project and name:

----
system:serviceaccount:<project>:<name>
----

For example, to add the *view* role to the *robot* service account in the
*top-secret* project:

====
----
$ oc policy add-role-to-user view system:serviceaccount:top-secret:robot
----
====

Every service account is also a member of two groups:

system:serviceaccounts:: Includes all service accounts in the system.
system:serviceaccounts:<project>:: Includes all service accounts in the
specified project.

For example, to allow all service accounts in all projects to view resources in
the *top-secret* project:

====
----
$ oc policy add-role-to-group view system:serviceaccounts -n top-secret
----
====

To allow all service accounts in the *managers* project to edit resources in the
*top-secret* project:

====
----
$ oc policy add-role-to-group edit system:serviceaccounts:managers -n top-secret
----
====

[[enabling-service-account-authentication]]
== Enabling Service Account Authentication

Service accounts authenticate to the API using tokens signed by a private RSA
key. The authentication layer verifies the signature using a matching public RSA
key.

To enable service account token generation, update the `*serviceAccountConfig*`
stanza in the *_/etc/origin/master/master-config.yml_* file on the master to
specify a `*privateKeyFile*` (for signing), and a matching public key file in
the `*publicKeyFiles*` list:

====
----
serviceAccountConfig:
  ...
  masterCA: ca.crt <1>
  privateKeyFile: serviceaccounts.private.key <2>
  publicKeyFiles:
  - serviceaccounts.public.key <3>
  - ...
----
<1> CA file used to validate the API server's serving certificate.
<2> Private RSA key file (for token signing).
<3> Public RSA key files (for token verification). If private key files are
provided, then the public key component is used. Multiple public key files can
be specified, and a token will be accepted if it can be validated by one of the
public keys. This allows rotation of the signing key, while still accepting
tokens generated by the previous signer.
====

[[managed-service-accounts]]
== Managed Service Accounts

Service accounts are required in each project to run builds, deployments, and
other pods. The `*managedNames*` setting in the
*_/etc/origin/master/master-config.yml_* file on the master controls which
service accounts are automatically created in every project:

====
----
serviceAccountConfig:
  ...
  managedNames: <1>
  - builder <2>
  - deployer <3>
  - default <4>
  - ...
----
<1> List of service accounts to automatically create in every project.
<2> A *builder* service account in each project is required by build pods, and is
given the *system:image-builder* role, which allows pushing images to any image
stream in the project using the internal container registry.
<3> A *deployer* service account in each project is required by deployment pods, and
is given the *system:deployer* role, which allows viewing and modifying
replication controllers and pods in the project.
<4> A *default* service account is used by all other pods unless they specify a
different service account.
====

All service accounts in a project are given the *system:image-puller* role,
which allows pulling images from any image stream in the project using the
internal container registry.

[[infrastructure-service-accounts]]
== Infrastructure Service Accounts

Several infrastructure controllers run using service account credentials. The
following service accounts are created in the {product-title} infrastructure
project (*openshift-infra*) at server start, and given the following roles
cluster-wide:

[cols="1,3",options="header"]
|====
|Service Account |Description

|*replication-controller*
|Assigned the *system:replication-controller* role

|*deployment-controller*
|Assigned the *system:deployment-controller* role

|*build-controller*
|Assigned the *system:build-controller* role. Additionally, the
*build-controller* service account is included in the privileged
xref:manage_scc.adoc#admin-guide-manage-scc[security context constraint] in order to create privileged
build pods.
|====

To configure the project where those service accounts are created, set the
`*openshiftInfrastructureNamespace*` field in in the
*_/etc/origin/master/master-config.yml_* file on the master:

====
----
policyConfig:
  ...
  openshiftInfrastructureNamespace: openshift-infra
----
====

[[service-accounts-and-secrets]]
== Service Accounts and Secrets

Set the `*limitSecretReferences*` field in the
*_/etc/origin/master/master-config.yml_* file on the master to `true` to require
pod secret references to be whitelisted by their service accounts. Set its value
to `false` to allow pods to reference any secret in the project.

====
----
serviceAccountConfig:
  ...
  limitSecretReferences: false
----
====
{'fraction_non_alphanumeric': 0.0958245466048081, 'fraction_numerical': 0.002699283002952341, 'mean_word_length': 4.738625363020329, 'pattern_counts': {'":': 0, '<': 37, '<?xml version=': 0, '>': 37, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2469832', 'n_tokens_mistral': 3257, 'n_tokens_neox': 3121, 'n_words': 1405}