CINXE.COM
Role based permissions (recommended) - Authentication and Authorization Service
<!doctype html> <html lang="en" class="no-js"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width,initial-scale=1"> <link rel="icon" href="../../assets/images/favicon.png"> <meta name="generator" content="mkdocs-1.3.1, mkdocs-material-8.5.3"> <title>Role based permissions (recommended) - Authentication and Authorization Service</title> <link rel="stylesheet" href="../../assets/stylesheets/main.7a952b86.min.css"> <link rel="stylesheet" href="../../assets/stylesheets/palette.cbb835fc.min.css"> <link rel="stylesheet" href="../../stylesheets/fonts.css"> <link rel="stylesheet" href="../../stylesheets/kuri-kuri.css"> <script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce((e,_)=>(e<<5)-e+_.charCodeAt(0),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script> </head> <body dir="ltr" data-md-color-scheme="" data-md-color-primary="none" data-md-color-accent="none"> <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off"> <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off"> <label class="md-overlay" for="__drawer"></label> <div data-md-component="skip"> <a href="#what-is-a-role" class="md-skip"> Skip to content </a> </div> <div data-md-component="announce"> </div> <header class="md-header" data-md-component="header"> <nav class="md-header__inner md-grid" aria-label="Header"> <a href="../.." title="Authentication and Authorization Service" class="md-header__button md-logo" aria-label="Authentication and Authorization Service" data-md-component="logo"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54Z"/></svg> </a> <label class="md-header__button md-icon" for="__drawer"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2Z"/></svg> </label> <div class="md-header__title" data-md-component="header-title"> <div class="md-header__ellipsis"> <div class="md-header__topic"> <span class="md-ellipsis"> Authentication and Authorization Service </span> </div> <div class="md-header__topic" data-md-component="header-topic"> <span class="md-ellipsis"> Role based permissions (recommended) </span> </div> </div> </div> <label class="md-header__button md-icon" for="__search"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg> </label> <div class="md-search" data-md-component="search" role="dialog"> <label class="md-search__overlay" for="__search"></label> <div class="md-search__inner" role="search"> <form class="md-search__form" name="search"> <input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required> <label class="md-search__icon md-icon" for="__search"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12Z"/></svg> </label> <nav class="md-search__options" aria-label="Search"> <button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41Z"/></svg> </button> </nav> </form> <div class="md-search__output"> <div class="md-search__scrollwrap" data-md-scrollfix> <div class="md-search-result" data-md-component="search-result"> <div class="md-search-result__meta"> Initializing search </div> <ol class="md-search-result__list"></ol> </div> </div> </div> </div> </div> <div class="md-header__source"> <a href="https://gitlab.cern.ch/authzsvc/docs/authzsvc-docs" title="Go to repository" class="md-source" data-md-component="source"> <div class="md-source__icon md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc.--><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81z"/></svg> </div> <div class="md-source__repository"> authzsvc-docs </div> </a> </div> </nav> </header> <div class="md-container" data-md-component="container"> <main class="md-main" data-md-component="main"> <div class="md-main__inner md-grid"> <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" > <div class="md-sidebar__scrollwrap"> <div class="md-sidebar__inner"> <nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0"> <label class="md-nav__title" for="__drawer"> <a href="../.." title="Authentication and Authorization Service" class="md-nav__button md-logo" aria-label="Authentication and Authorization Service" data-md-component="logo"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54Z"/></svg> </a> Authentication and Authorization Service </label> <div class="md-nav__source"> <a href="https://gitlab.cern.ch/authzsvc/docs/authzsvc-docs" title="Go to repository" class="md-source" data-md-component="source"> <div class="md-source__icon md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc.--><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81z"/></svg> </div> <div class="md-source__repository"> authzsvc-docs </div> </a> </div> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../.." class="md-nav__link"> CERN Authentication and Authorization Services </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_2" type="checkbox" id="__nav_2" > <label class="md-nav__link" for="__nav_2"> User authentication <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="User authentication" data-md-level="1"> <label class="md-nav__title" for="__nav_2"> <span class="md-nav__icon md-icon"></span> User authentication </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../user-documentation/authentication-options/" class="md-nav__link"> Authentication options </a> </li> <li class="md-nav__item"> <a href="../../user-documentation/two-factor-authentication/" class="md-nav__link"> Two factor authentication </a> </li> <li class="md-nav__item"> <a href="../../user-documentation/kerberos-authentication/" class="md-nav__link"> Kerberos </a> </li> <li class="md-nav__item"> <a href="../../user-documentation/time-limits/" class="md-nav__link"> Time limits </a> </li> <li class="md-nav__item"> <a href="../../user-documentation/autologon/" class="md-nav__link"> Autologon </a> </li> <li class="md-nav__item"> <a href="../../user-documentation/account-lifecycle/" class="md-nav__link"> Account Lifecycle </a> </li> <li class="md-nav__item"> <a href="../../user-documentation/unconfirmed-identities/" class="md-nav__link"> Unconfirmed identities </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--active md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_3" type="checkbox" id="__nav_3" checked> <label class="md-nav__link" for="__nav_3"> Securing applications <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="Securing applications" data-md-level="1"> <label class="md-nav__title" for="__nav_3"> <span class="md-nav__icon md-icon"></span> Securing applications </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../application-configuration/" class="md-nav__link"> Configuring your application </a> </li> <li class="md-nav__item"> <a href="../adding-application/" class="md-nav__link"> Adding your application to the service </a> </li> <li class="md-nav__item"> <a href="../permission-scheme/" class="md-nav__link"> Defining the permissions scheme </a> </li> <li class="md-nav__item md-nav__item--active"> <input class="md-nav__toggle md-toggle" data-md-toggle="toc" type="checkbox" id="__toc"> <label class="md-nav__link md-nav__link--active" for="__toc"> Role based permissions (recommended) <span class="md-nav__icon md-icon"></span> </label> <a href="./" class="md-nav__link md-nav__link--active"> Role based permissions (recommended) </a> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class="md-nav__title" for="__toc"> <span class="md-nav__icon md-icon"></span> Table of contents </label> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <li class="md-nav__item"> <a href="#what-is-a-role" class="md-nav__link"> What is a role? </a> </li> <li class="md-nav__item"> <a href="#how-do-roles-work" class="md-nav__link"> How do roles work </a> <nav class="md-nav" aria-label="How do roles work"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#role-requirements" class="md-nav__link"> Role requirements </a> </li> <li class="md-nav__item"> <a href="#restricting-access-with-required-roles" class="md-nav__link"> Restricting access with required roles </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#default-role" class="md-nav__link"> Default role </a> </li> <li class="md-nav__item"> <a href="#defining-a-role" class="md-nav__link"> Defining a role </a> </li> <li class="md-nav__item"> <a href="#mapping-roles-to-groups" class="md-nav__link"> Mapping roles to groups </a> </li> <li class="md-nav__item"> <a href="#examples" class="md-nav__link"> Examples </a> <nav class="md-nav" aria-label="Examples"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#cern-accounts-and-admins" class="md-nav__link"> CERN accounts and admins </a> </li> <li class="md-nav__item"> <a href="#specific-teams-with-2fa" class="md-nav__link"> Specific teams with 2FA </a> </li> <li class="md-nav__item"> <a href="#anyone-with-2fa" class="md-nav__link"> Anyone with 2FA </a> </li> <li class="md-nav__item"> <a href="#only-known-cern-people" class="md-nav__link"> Only known CERN people </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../group-based-permissions/" class="md-nav__link"> Group based permissions </a> </li> <li class="md-nav__item"> <a href="../sso-registration/" class="md-nav__link"> Registering your application to SSO </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_3_7" type="checkbox" id="__nav_3_7" > <label class="md-nav__link" for="__nav_3_7"> SAML <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="SAML" data-md-level="2"> <label class="md-nav__title" for="__nav_3_7"> <span class="md-nav__icon md-icon"></span> SAML </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../user-documentation/saml/saml/" class="md-nav__link"> About </a> </li> <li class="md-nav__item"> <a href="../../user-documentation/saml/config/" class="md-nav__link"> Configuration </a> </li> <li class="md-nav__item"> <a href="../../user-documentation/saml/shibboleth-integration/" class="md-nav__link"> Shibboleth integration </a> </li> <li class="md-nav__item"> <a href="../../user-documentation/saml/shibboleth-migration/" class="md-nav__link"> Shibboleth migration from the old SSO </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_3_8" type="checkbox" id="__nav_3_8" > <label class="md-nav__link" for="__nav_3_8"> OIDC <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="OIDC" data-md-level="2"> <label class="md-nav__title" for="__nav_3_8"> <span class="md-nav__icon md-icon"></span> OIDC </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../user-documentation/oidc/oidc/" class="md-nav__link"> About </a> </li> <li class="md-nav__item"> <a href="../../user-documentation/oidc/token-requests/" class="md-nav__link"> Token Requests </a> </li> <li class="md-nav__item"> <a href="../../user-documentation/oidc/scopes/" class="md-nav__link"> Scopes </a> </li> <li class="md-nav__item"> <a href="../../user-documentation/oidc/config/" class="md-nav__link"> OIDC configuration and usage </a> </li> <li class="md-nav__item"> <a href="../../user-documentation/oidc/apache/" class="md-nav__link"> Apache configuration </a> </li> <li class="md-nav__item"> <a href="../../user-documentation/oidc/securing-apis/" class="md-nav__link"> Securing APIs </a> </li> <li class="md-nav__item"> <a href="../../user-documentation/oidc/api-access/" class="md-nav__link"> API Access </a> </li> <li class="md-nav__item"> <a href="../../user-documentation/oidc/exchange-for-api/" class="md-nav__link"> Token Exchange </a> </li> <li class="md-nav__item"> <a href="../../user-documentation/oidc/device-code/" class="md-nav__link"> Device Code </a> </li> <li class="md-nav__item"> <a href="../../user-documentation/oidc/libraries/" class="md-nav__link"> Suggested libraries </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../examples/" class="md-nav__link"> Examples </a> </li> <li class="md-nav__item"> <a href="../qa-environment/" class="md-nav__link"> QA Environment </a> </li> <li class="md-nav__item"> <a href="../command-line-tools/" class="md-nav__link"> Command line tools </a> </li> <li class="md-nav__item"> <a href="../../user-documentation/faqs/" class="md-nav__link"> FAQs </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_4" type="checkbox" id="__nav_4" > <label class="md-nav__link" for="__nav_4"> Group Management System <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="Group Management System" data-md-level="1"> <label class="md-nav__title" for="__nav_4"> <span class="md-nav__icon md-icon"></span> Group Management System </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../roadmap/group-missing-features/" class="md-nav__link"> Missing features </a> </li> <li class="md-nav__item"> <a href="../../groups/special-groups/" class="md-nav__link"> Special groups </a> </li> <li class="md-nav__item"> <a href="../../groups/dynamic-guidance/" class="md-nav__link"> Dynamic groups </a> </li> <li class="md-nav__item"> <a href="../../groups/csv/" class="md-nav__link"> CSV </a> </li> <li class="md-nav__item"> <a href="../../groups/e-groups-to-gms-sync-scenario/" class="md-nav__link"> E-Groups to GMS transition </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_5" type="checkbox" id="__nav_5" > <label class="md-nav__link" for="__nav_5"> Resources lifecycle and eligibility <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="Resources lifecycle and eligibility" data-md-level="1"> <label class="md-nav__title" for="__nav_5"> <span class="md-nav__icon md-icon"></span> Resources lifecycle and eligibility </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../resources/resources/" class="md-nav__link"> Introduction </a> </li> <li class="md-nav__item"> <a href="../../resources/resource-lifecycle-integration/" class="md-nav__link"> Integration </a> </li> <li class="md-nav__item"> <a href="../../resources/resource-states/" class="md-nav__link"> Resource States </a> </li> <li class="md-nav__item"> <a href="../../resources/push-rest-api/" class="md-nav__link"> Resources REST API (push) </a> </li> <li class="md-nav__item"> <a href="../../resources/policies/" class="md-nav__link"> Custom Resource Policies </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6" type="checkbox" id="__nav_6" > <label class="md-nav__link" for="__nav_6"> Documents <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="Documents" data-md-level="1"> <label class="md-nav__title" for="__nav_6"> <span class="md-nav__icon md-icon"></span> Documents </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../documents/why-keycloak/" class="md-nav__link"> Why Keycloak </a> </li> <li class="md-nav__item"> <a href="../../documents/presentations/" class="md-nav__link"> Presentations </a> </li> <li class="md-nav__item"> <a href="../../documents/our-contributions/" class="md-nav__link"> Our contributions to Keycloak </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_7" type="checkbox" id="__nav_7" > <label class="md-nav__link" for="__nav_7"> Services <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="Services" data-md-level="1"> <label class="md-nav__title" for="__nav_7"> <span class="md-nav__icon md-icon"></span> Services </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../services/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../../services/instances/" class="md-nav__link"> Links to instances </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_7_3" type="checkbox" id="__nav_7_3" > <label class="md-nav__link" for="__nav_7_3"> Authorization Service API <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="Authorization Service API" data-md-level="2"> <label class="md-nav__title" for="__nav_7_3"> <span class="md-nav__icon md-icon"></span> Authorization Service API </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../authzsvc/overview/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../../authzsvc/managed-applications/" class="md-nav__link"> Managing applications for other users </a> </li> <li class="md-nav__item"> <a href="../../authzsvc/roles/" class="md-nav__link"> Role definitions </a> </li> <li class="md-nav__item"> <a href="../../authzsvc/model/" class="md-nav__link"> Model (attributes) </a> </li> <li class="md-nav__item"> <a href="../../authzsvc/examples/" class="md-nav__link"> Examples </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_8" type="checkbox" id="__nav_8" > <label class="md-nav__link" for="__nav_8"> Help <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="Help" data-md-level="1"> <label class="md-nav__title" for="__nav_8"> <span class="md-nav__icon md-icon"></span> Help </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../trouble-shooting/edugain-authentication/" class="md-nav__link"> eduGAIN Authentication </a> </li> <li class="md-nav__item"> <a href="../../trouble-shooting/2fa-tips/" class="md-nav__link"> 2FA Tips </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../../privacy-notice/" class="md-nav__link"> Privacy notice </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_10" type="checkbox" id="__nav_10" > <label class="md-nav__link" for="__nav_10"> Migration notes <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" aria-label="Migration notes" data-md-level="1"> <label class="md-nav__title" for="__nav_10"> <span class="md-nav__icon md-icon"></span> Migration notes </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../migrations/keycloak24/" class="md-nav__link"> Keycloak 24 </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../../contact/" class="md-nav__link"> Contact </a> </li> </ul> </nav> </div> </div> </div> <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" > <div class="md-sidebar__scrollwrap"> <div class="md-sidebar__inner"> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class="md-nav__title" for="__toc"> <span class="md-nav__icon md-icon"></span> Table of contents </label> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <li class="md-nav__item"> <a href="#what-is-a-role" class="md-nav__link"> What is a role? </a> </li> <li class="md-nav__item"> <a href="#how-do-roles-work" class="md-nav__link"> How do roles work </a> <nav class="md-nav" aria-label="How do roles work"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#role-requirements" class="md-nav__link"> Role requirements </a> </li> <li class="md-nav__item"> <a href="#restricting-access-with-required-roles" class="md-nav__link"> Restricting access with required roles </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#default-role" class="md-nav__link"> Default role </a> </li> <li class="md-nav__item"> <a href="#defining-a-role" class="md-nav__link"> Defining a role </a> </li> <li class="md-nav__item"> <a href="#mapping-roles-to-groups" class="md-nav__link"> Mapping roles to groups </a> </li> <li class="md-nav__item"> <a href="#examples" class="md-nav__link"> Examples </a> <nav class="md-nav" aria-label="Examples"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#cern-accounts-and-admins" class="md-nav__link"> CERN accounts and admins </a> </li> <li class="md-nav__item"> <a href="#specific-teams-with-2fa" class="md-nav__link"> Specific teams with 2FA </a> </li> <li class="md-nav__item"> <a href="#anyone-with-2fa" class="md-nav__link"> Anyone with 2FA </a> </li> <li class="md-nav__item"> <a href="#only-known-cern-people" class="md-nav__link"> Only known CERN people </a> </li> </ul> </nav> </li> </ul> </nav> </div> </div> </div> <div class="md-content" data-md-component="content"> <article class="md-content__inner md-typeset"> <a href="https://gitlab.cern.ch/authzsvc/docs/authzsvc-docs/-/blob/master/docs/applications/role-based-permissions.md" title="Edit this page" class="md-content__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20.71 7.04c.39-.39.39-1.04 0-1.41l-2.34-2.34c-.37-.39-1.02-.39-1.41 0l-1.84 1.83 3.75 3.75M3 17.25V21h3.75L17.81 9.93l-3.75-3.75L3 17.25Z"/></svg> </a> <h1>Role based permissions (recommended)</h1> <h2 id="what-is-a-role">What is a role?</h2> <p>A <strong>role</strong> is an identifier for a set of permissions in your application, that can be assigned to a group of users. </p> <p>The authentication token provided to users when they login to your application will contain all the roles that the users have <em>in your application only</em>, in a special claim named <code>cern_roles</code> for OIDC or <code>CernRoles</code>for SAML.</p> <p>The concept of roles was introduced to <strong>let applications enforce their own authorization scheme without querying for groups membership</strong>.</p> <p>Since a user can potentially be a member of many groups, if we were putting all groups memberships in a user's token, we would reach a point where the token becomes so big that browsers cannot handle it. </p> <p>This forced applications to query an external groups data source (generally LDAP) to determine if a user is a member of a group granting certain privileges. </p> <p>If you define roles for your application, the authentication tokens of the users accessing your application will always contain all the relevant information for your authorization decisions, without being bloated with irrelevant groups memberships. </p> <p>For example, a users's token could tell your application that that user has the <code>application_administrator</code> role, without containing the irrelevant information that the user is a member of <code>vogons-at-cern</code> group.</p> <h2 id="how-do-roles-work">How do roles work</h2> <p>As we said, roles can be assigned to groups of users: when a user logs in to your application, their Single Sign-on token will contain all the roles that are mapped to any of the groups they are member of. Alternatively, roles may apply to <strong>all authenticated users</strong> rather than identifying specific groups; this is useful if, for example, you would like to know whether all users have authenticated with Multi-Factor or not.</p> <p>Please note that <strong>group membership is evaluated recursively</strong>. <br /> Example:</p> <ul> <li>You assign the role <code>application_users</code> to the group <code>building-XYZ</code>.</li> <li>The group <code>building-XYZ-1st-floor</code> is member of <code>building-XYZ</code>.</li> <li>A user who is member of the group <code>building-XYZ-1st-floor</code> logs in to your application.</li> <li>The user's token contains the role <code>application_users</code>.</li> </ul> <h3 id="role-requirements">Role requirements</h3> <p>Roles can define additional <strong>authentication requirements</strong> for <em>Multi-Factor Authentication</em> (MFA) and <em>Level Of Assurance</em> (LOA).</p> <p><strong>Multi-Factor Authentication (MFA)</strong> is an identity verification process requiring more than one method of authentication from the user (for example, a password and a one-time code). </p> <p>Multi-factor authentication provides a higher degree of security than regular (single-factor) authentication.<br /> If you enforce the MFA requirement on a certain role, a user logging in to your application will get a token containing that role only if they are member of a group mapped to the role <em>and</em> they logged in using multi-factor authentication.</p> <p>The <strong>Level of Assurance (LOA)</strong> is the degree of confidence in the identity verification process established by the authentication provider issuing the user's credentials. </p> <p>You can select specific LOA values, as follows: </p> <ul> <li>CERN: the user must have shown in person, with a valid ID document, at a secretariat or other registration office.</li> <li>EduGain with Sirtfi: the user is authenticated by an institution that is part of the EduGain identity federation (and that follows security practices called Sirtfi). These users are typically members of universities or other research institutes.</li> <li>Social accounts: anybody can register such an account, with little control or identity verification.</li> </ul> <p>If you enforce the LOA requirement on a certain role, a user logging in to your application will get a token containing that role only if they logged in using an account from an identity provider with a sufficiently high LOA.</p> <p>If you wish to restrict access to any known CERN person, regardless of the LOA, please see the example further down this documentation.</p> <h3 id="restricting-access-with-required-roles">Restricting access with required roles</h3> <p>You can choose to block access to some users at the SSO level by setting up a <strong>required role</strong>. </p> <p>If a role is required, users who do not belong to that role will not be able to access your application: after authenticating, they will receive an access denied error from the Single Sign On service.</p> <p>For example, if you want to limit access to your application only to users above a certain level of assurance, you could setup a required role, tick the option to apply the role to all users, then set a LoA requirement on the role.</p> <h2 id="default-role">Default role</h2> <p>When you register your application for SSO, a default role is added to only allow users with a CERN or eduGAIN account to authenticate. You can modify this role if you would also like to allow social accounts (e.g. Google or Facebook) or guest accounts (self-registration, formerly known as Lightweight Accounts).</p> <h2 id="defining-a-role">Defining a role</h2> <p>You can define roles from the application page:</p> <p><img alt="add a role" src="../../images/add-a-role.png" /></p> <p>The <strong>Role Name</strong> is a readable name for your role.</p> <p>The <strong>Unique Identifier</strong> is a unique identifier for your role:</p> <ul> <li>it must be unique for your application</li> <li>it must start with a lowercase letter</li> <li>it can contain only lowercase letters, numbers, dashes and underscores</li> <li>must be between 3 and 64 characters long</li> </ul> <p>The unique identifier of the role <strong>is the value that will be passed in the <code>resource_access.{aplication_name}.roles</code> claim of the user token</strong>, i.e. the value that your application will need to check to perform authorization decisions.</p> <p>If you want to restrict access to your application only to users belonging to a certain role, tick the <strong>"this role is required"</strong> checkbox.</p> <p>If you want to require that users authenticate with multi-factor authentication to your application to obtain a certain role, tick the <strong>"users with this role require multifactor authentication"</strong> checkbox.</p> <blockquote> <p>Note: If this box is ticked the application will redirect the user to login with Two-factor authentication by appending <code>only2fa=true</code> to the URL query parameters.</p> </blockquote> <p>If you want a role to apply to all authenticated users, regardless of groups, select <strong>"This role applies to all authenticated users"</strong>.</p> <h2 id="mapping-roles-to-groups">Mapping roles to groups</h2> <p>Now that we have defined the roles for our application, we need to map each of them to one or more groups, so that users that are members of those group will obtain the corresponding roles in the SSO token (provided that MFA and LOA requirements for the role are met).</p> <p><img alt="roles list" src="../../images/roles-list.png" /></p> <p>Clicking on the green <em>"Assign role to groups"</em> button in the roles list will let you define the groups that are mapped to that role.</p> <p><img alt="roles list" src="../../images/mapping-role-to-groups.png" /></p> <h2 id="examples">Examples</h2> <p>The roles system is very flexible. A couple of examples are included here to help you get started.</p> <h3 id="cern-accounts-and-admins">CERN accounts and admins</h3> <blockquote> <p>I run a site for the library; only CERN accounts should be able to access and, in addition, I need to identify librarians (in group <code>librarians</code>) so that they can be access the management area.</p> </blockquote> <ol> <li>Create a role called <code>allowed-users</code>, select <code>Required</code>, select <code>This role applies to all users</code> and set the minimum Level of Assurance to <code>CERN (Highest)</code> </li> <li>Configure a second role called <code>librarian</code>, do not select <code>Required</code>, once it's created link it to the group <code>librarians</code></li> </ol> <p><img alt="library roles" src="../../images/library-roles.png" /></p> <h3 id="specific-teams-with-2fa">Specific teams with 2FA</h3> <blockquote> <p>I run a site for the finance department; people from the finance team (in group <code>finance-team</code>) should be able to access and they must use second factor authentication. In addition, some IT support staff (in group <code>finance-it-support</code>) must be able to log in and be identified as IT support.</p> </blockquote> <p>In this case we need to think a bit harder since users must have ALL required roles in order to authenticate. Consequently the IT staff must also use 2FA if we want to enforce 2FA at the SSO level. You could also choose to make all roles optional and process them within your application.</p> <ol> <li>Create a role called <code>allowed-users</code>, select <code>Required</code>, select <code>Multifactor Required</code>, once it's created link it to two groups, <code>finance-team</code> and <code>finance-it-support</code></li> <li>Create a role called <code>it-support</code>, do not select <code>Required</code>, once it's created link it to the group e.g. <code>finance-it-support</code></li> </ol> <p><img alt="finance roles" src="../../images/finance-roles.png" /></p> <h3 id="anyone-with-2fa">Anyone with 2FA</h3> <blockquote> <p>Anybody should be able to access my site, but they must use second factor authentication</p> </blockquote> <p>In this case we need to create a required role, that requires Multifactor and applies to all users (i.e. we don't link it to specific groups).</p> <p><img alt="required role" src="../../images/required-role.png" /></p> <h3 id="only-known-cern-people">Only known CERN people</h3> <blockquote> <p>I only want known CERN people to be able to log in, this should include ex-employees as well as currently active CERN members.</p> </blockquote> <p>Create a role with LoA = <code>Social (lowest)</code> and select <code>Required</code>. The link it to 2 groups: <code>cern-active-users</code> and <code>cern-non-active-users</code>. These two groups together contain all the people known by CERN.</p> <p><img alt="CERN role" src="../../images/role-known-cern-people.png" /></p> </article> </div> </div> </main> <footer class="md-footer"> <nav class="md-footer__inner md-grid" aria-label="Footer" > <a href="../permission-scheme/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Defining the permissions scheme" rel="prev"> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12Z"/></svg> </div> <div class="md-footer__title"> <div class="md-ellipsis"> <span class="md-footer__direction"> Previous </span> Defining the permissions scheme </div> </div> </a> <a href="../group-based-permissions/" class="md-footer__link md-footer__link--next" aria-label="Next: Group based permissions" rel="next"> <div class="md-footer__title"> <div class="md-ellipsis"> <span class="md-footer__direction"> Next </span> Group based permissions </div> </div> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11H4Z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class="md-copyright"> Made with <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener"> Material for MkDocs </a> </div> </div> </div> </footer> </div> <div class="md-dialog" data-md-component="dialog"> <div class="md-dialog__inner md-typeset"></div> </div> <script id="__config" type="application/json">{"base": "../..", "features": [], "search": "../../assets/javascripts/workers/search.5bf1dace.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.config.lang": "en", "search.config.pipeline": "trimmer, stopWordFilter", "search.config.separator": "[\\s\\-]+", "search.placeholder": "Search", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version.title": "Select version"}}</script> <script src="../../assets/javascripts/bundle.37e9125f.min.js"></script> </body> </html>