istio.io/content/docs/reference/config/authorization/istio.rbac.v1alpha1/index.html

---
title: RBAC
description: Configuration for Role Based Access Control
location: https://istio.io/docs/reference/config/authorization/istio.rbac.v1alpha1.html
layout: protoc-gen-docs
generator: protoc-gen-docs
number_of_entries: 9
---
<p>Istio RBAC (Role Based Access Control) defines ServiceRole and ServiceRoleBinding
objects.</p>

<p>A ServiceRole specification includes a list of rules (permissions). Each rule has
the following standard fields:</p>

<ul>
<li>services: a list of services.</li>
<li>methods: HTTP methods. In the case of gRPC, this field is ignored because the value is always &ldquo;POST&rdquo;.</li>
<li>paths: HTTP paths or gRPC methods. Note that gRPC methods should be
presented in the form of &ldquo;packageName.serviceName/methodName&rdquo;.</li>
</ul>

<p>In addition to the standard fields, operators can also use custom keys in the <code>constraints</code> field,
the supported keys are listed in the &ldquo;constraints and properties&rdquo; page.</p>

<p>Below is an example of ServiceRole object &ldquo;product-viewer&rdquo;, which has &ldquo;read&rdquo; (&ldquo;GET&rdquo; and &ldquo;HEAD&rdquo;)
access to &ldquo;products.svc.cluster.local&rdquo; service at versions &ldquo;v1&rdquo; and &ldquo;v2&rdquo;. &ldquo;path&rdquo; is not specified,
so it applies to any path in the service.</p>

<pre><code class="language-yaml">apiVersion: &quot;config.istio.io/v1alpha2&quot;
kind: ServiceRole
metadata:
  name: products-viewer
  namespace: default
spec:
  rules:
  - services: [&quot;products.svc.cluster.local&quot;]
    methods: [&quot;GET&quot;, &quot;HEAD&quot;]
    constraints:
    - key: &quot;destination.labels[version]&quot;
      value: [&quot;v1&quot;, &quot;v2&quot;]
</code></pre>

<p>A ServiceRoleBinding specification includes two parts:</p>

<ul>
<li>The <code>roleRef</code> field that refers to a ServiceRole object in the same namespace.</li>
<li>A list of <code>subjects</code> that are assigned the roles.</li>
</ul>

<p>In addition to a simple <code>user</code> field, operators can also use custom keys in the <code>properties</code> field,
the supported keys are listed in the &ldquo;constraints and properties&rdquo; page.</p>

<p>Below is an example of ServiceRoleBinding object &ldquo;test-binding-products&rdquo;, which binds two subjects
to ServiceRole &ldquo;product-viewer&rdquo;:</p>

<ul>
<li>User &ldquo;alice@yahoo.com&rdquo;</li>
<li>Services in &ldquo;abc&rdquo; namespace.</li>
</ul>

<pre><code class="language-yaml">apiVersion: &quot;config.istio.io/v1alpha2&quot;
kind: ServiceRoleBinding
metadata:
  name: test-binding-products
  namespace: default
spec:
  subjects:
  - user: alice@yahoo.com
  - properties:
      source.namespace: &quot;abc&quot;
  roleRef:
    kind: ServiceRole
    name: &quot;products-viewer&quot;
</code></pre>

<h2 id="AccessRule">AccessRule</h2>
<section>
<p>AccessRule defines a permission to access a list of services.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="AccessRule-services">
<td><code>services</code></td>
<td><code>string[]</code></td>
<td>
<p>Required. A list of service names.
Exact match, prefix match, and suffix match are supported for service names.
For example, the service name &ldquo;bookstore.mtv.cluster.local&rdquo; matches
&ldquo;bookstore.mtv.cluster.local&rdquo; (exact match), or &ldquo;bookstore<em>&rdquo; (prefix match),
or &ldquo;</em>.mtv.cluster.local&rdquo; (suffix match).
If set to [&ldquo;*&rdquo;], it refers to all services in the namespace.</p>

</td>
</tr>
<tr id="AccessRule-paths">
<td><code>paths</code></td>
<td><code>string[]</code></td>
<td>
<p>Optional. A list of HTTP paths or gRPC methods.
gRPC methods must be presented as fully-qualified name in the form of
packageName.serviceName/methodName.
Exact match, prefix match, and suffix match are supported for paths.
For example, the path &ldquo;/books/review&rdquo; matches
&ldquo;/books/review&rdquo; (exact match), or &ldquo;/books/<em>&rdquo; (prefix match),
or &ldquo;</em>/review&rdquo; (suffix match).
If not specified, it applies to any path.</p>

</td>
</tr>
<tr id="AccessRule-methods">
<td><code>methods</code></td>
<td><code>string[]</code></td>
<td>
<p>Optional. A list of HTTP methods (e.g., &ldquo;GET&rdquo;, &ldquo;POST&rdquo;).
It is ignored in gRPC case because the value is always &ldquo;POST&rdquo;.
If set to [&ldquo;*&rdquo;] or not specified, it applies to any method.</p>

</td>
</tr>
<tr id="AccessRule-constraints">
<td><code>constraints</code></td>
<td><code><a href="#AccessRule-Constraint">AccessRule.Constraint[]</a></code></td>
<td>
<p>Optional. Extra constraints in the ServiceRole specification.
The above ServiceRole example shows an example of constraint &ldquo;version&rdquo;.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="AccessRule-Constraint">AccessRule.Constraint</h2>
<section>
<p>Definition of a custom constraint. The supported keys are listed in the &ldquo;constraint and properties&rdquo; page.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="AccessRule-Constraint-key">
<td><code>key</code></td>
<td><code>string</code></td>
<td>
<p>Key of the constraint.</p>

</td>
</tr>
<tr id="AccessRule-Constraint-values">
<td><code>values</code></td>
<td><code>string[]</code></td>
<td>
<p>List of valid values for the constraint.
Exact match, prefix match, and suffix match are supported for constraint values.
For example, the value &ldquo;v1alpha2&rdquo; matches
&ldquo;v1alpha2&rdquo; (exact match), or &ldquo;v1<em>&rdquo; (prefix match),
or &ldquo;</em>alpha2&rdquo; (suffix match).</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="RbacConfig">RbacConfig</h2>
<section>
<p>RbacConfig defines the global config to control Istio RBAC behavior.
This Custom Resource is a singleton where only one Custom Resource should be created globally in
the mesh and the namespace should be the same to other Istio components, which usually is istio-system.
Note: This is enforced in both istioctl and server side, new Custom Resource will be rejected if found any
existing one, the user should either delete the existing one or change the existing one directly.</p>

<p>Below is an example of RbacConfig object &ldquo;istio-rbac-config&rdquo; which enables Istio RBAC for all
services in the default namespace.</p>

<pre><code class="language-yaml">apiVersion: &quot;config.istio.io/v1alpha2&quot;
kind: RbacConfig
metadata:
  name: default
  namespace: istio-system
spec:
  mode: ON_WITH_INCLUSION
  inclusion:
    namespaces: [ &quot;default&quot; ]
</code></pre>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="RbacConfig-mode">
<td><code>mode</code></td>
<td><code><a href="#RbacConfig-Mode">RbacConfig.Mode</a></code></td>
<td>
<p>Istio RBAC mode.</p>

</td>
</tr>
<tr id="RbacConfig-inclusion">
<td><code>inclusion</code></td>
<td><code><a href="#RbacConfig-Target">RbacConfig.Target</a></code></td>
<td>
<p>A list of services or namespaces that should be enforced by Istio RBAC policies. Note: This field have
effect only when mode is ON<em>WITH</em>INCLUSION and will be ignored for any other modes.</p>

</td>
</tr>
<tr id="RbacConfig-exclusion">
<td><code>exclusion</code></td>
<td><code><a href="#RbacConfig-Target">RbacConfig.Target</a></code></td>
<td>
<p>A list of services or namespaces that should not be enforced by Istio RBAC policies. Note: This field have
effect only when mode is ON<em>WITH</em>EXCLUSION and will be ignored for any other modes.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="RbacConfig-Mode">RbacConfig.Mode</h2>
<section>
<table class="enum-values">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="RbacConfig-Mode-OFF">
<td><code>OFF</code></td>
<td>
<p>Disable Istio RBAC completely, any other config in RbacConfig will be ignored and Istio RBAC policies
will not be enforced.</p>

</td>
</tr>
<tr id="RbacConfig-Mode-ON">
<td><code>ON</code></td>
<td>
<p>Enable Istio RBAC for all services and namespaces.</p>

</td>
</tr>
<tr id="RbacConfig-Mode-ON_WITH_INCLUSION">
<td><code>ON_WITH_INCLUSION</code></td>
<td>
<p>Enable Istio RBAC only for services and namespaces specified in the inclusion field. Any other
services and namespaces not in the inclusion field will not be enforced by Istio RBAC policies.</p>

</td>
</tr>
<tr id="RbacConfig-Mode-ON_WITH_EXCLUSION">
<td><code>ON_WITH_EXCLUSION</code></td>
<td>
<p>Enable Istio RBAC for all services and namespaces except those specified in the exclusion field. Any other
services and namespaces not in the exclusion field will be enforced by Istio RBAC policies.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="RbacConfig-Target">RbacConfig.Target</h2>
<section>
<p>Target defines a list of services or namespaces.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="RbacConfig-Target-services">
<td><code>services</code></td>
<td><code>string[]</code></td>
<td>
<p>A list of services.</p>

</td>
</tr>
<tr id="RbacConfig-Target-namespaces">
<td><code>namespaces</code></td>
<td><code>string[]</code></td>
<td>
<p>A list of namespaces.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="RoleRef">RoleRef</h2>
<section>
<p>RoleRef refers to a role object.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="RoleRef-kind">
<td><code>kind</code></td>
<td><code>string</code></td>
<td>
<p>Required. The type of the role being referenced.
Currently, &ldquo;ServiceRole&rdquo; is the only supported value for &ldquo;kind&rdquo;.</p>

</td>
</tr>
<tr id="RoleRef-name">
<td><code>name</code></td>
<td><code>string</code></td>
<td>
<p>Required. The name of the ServiceRole object being referenced.
The ServiceRole object must be in the same namespace as the ServiceRoleBinding
object.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="ServiceRole">ServiceRole</h2>
<section>
<p>ServiceRole specification contains a list of access rules (permissions).
This represent the &ldquo;Spec&rdquo; part of the ServiceRole object. The name and namespace
of the ServiceRole is specified in &ldquo;metadata&rdquo; section of the ServiceRole object.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="ServiceRole-rules">
<td><code>rules</code></td>
<td><code><a href="#AccessRule">AccessRule[]</a></code></td>
<td>
<p>Required. The set of access rules (permissions) that the role has.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="ServiceRoleBinding">ServiceRoleBinding</h2>
<section>
<p>ServiceRoleBinding assigns a ServiceRole to a list of subjects.
This represents the &ldquo;Spec&rdquo; part of the ServiceRoleBinding object. The name and namespace
of the ServiceRoleBinding is specified in &ldquo;metadata&rdquo; section of the ServiceRoleBinding
object.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="ServiceRoleBinding-subjects">
<td><code>subjects</code></td>
<td><code><a href="#Subject">Subject[]</a></code></td>
<td>
<p>Required. List of subjects that are assigned the ServiceRole object.</p>

</td>
</tr>
<tr id="ServiceRoleBinding-roleRef">
<td><code>roleRef</code></td>
<td><code><a href="#RoleRef">RoleRef</a></code></td>
<td>
<p>Required. Reference to the ServiceRole object.</p>

</td>
</tr>
</tbody>
</table>
</section>
<h2 id="Subject">Subject</h2>
<section>
<p>Subject defines an identity. The identity is either a user or identified by a set of <code>properties</code>.
The supported keys in <code>properties</code> are listed in &ldquo;constraint and properties&rdquo; page.</p>

<table class="message-fields">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr id="Subject-user">
<td><code>user</code></td>
<td><code>string</code></td>
<td>
<p>Optional. The user name/ID that the subject represents.</p>

</td>
</tr>
<tr id="Subject-properties">
<td><code>properties</code></td>
<td><code>map&lt;string,&nbsp;string&gt;</code></td>
<td>
<p>Optional. The set of properties that identify the subject.
The above ServiceRoleBinding example shows an example of property &ldquo;source.namespace&rdquo;.</p>

</td>
</tr>
</tbody>
</table>
</section>