Overview - 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>Overview - 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="#authorization-service-api" 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"> Overview </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"><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"><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--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_3" type="checkbox" id="__nav_3" > <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="../../applications/application-configuration/" class="md-nav__link"> Configuring your application </a> </li> <li class="md-nav__item"> <a href="../../applications/adding-application/" class="md-nav__link"> Adding your application to the service </a> </li> <li class="md-nav__item"> <a href="../../applications/permission-scheme/" class="md-nav__link"> Defining the permissions scheme </a> </li> <li class="md-nav__item"> <a href="../../applications/role-based-permissions/" class="md-nav__link"> Role based permissions (recommended) </a> </li> <li class="md-nav__item"> <a href="../../applications/group-based-permissions/" class="md-nav__link"> Group based permissions </a> </li> <li class="md-nav__item"> <a href="../../applications/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="../../applications/examples/" class="md-nav__link"> Examples </a> </li> <li class="md-nav__item"> <a href="../../applications/qa-environment/" class="md-nav__link"> QA Environment </a> </li> <li class="md-nav__item"> <a href="../../applications/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--active md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_7" type="checkbox" id="__nav_7" checked> <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--active md-nav__item--nested"> <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_7_3" type="checkbox" id="__nav_7_3" checked> <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 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"> Overview <span class="md-nav__icon md-icon"></span> </label> <a href="./" class="md-nav__link md-nav__link--active"> Overview </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="#api-endpoints" class="md-nav__link"> API Endpoints </a> </li> <li class="md-nav__item"> <a href="#how-to-use-the-authorization-service-api" class="md-nav__link"> How to use the Authorization Service API </a> </li> <li class="md-nav__item"> <a href="#querying-with-pagination" class="md-nav__link"> Querying with pagination </a> </li> <li class="md-nav__item"> <a href="#requesting-permissions" class="md-nav__link"> Requesting Permissions </a> </li> <li class="md-nav__item"> <a href="#querying-computed-fields" class="md-nav__link"> Querying computed fields </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../managed-applications/" class="md-nav__link"> Managing applications for other users </a> </li> <li class="md-nav__item"> <a href="../roles/" class="md-nav__link"> Role definitions </a> </li> <li class="md-nav__item"> <a href="../model/" class="md-nav__link"> Model (attributes) </a> </li> <li class="md-nav__item"> <a href="../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="#api-endpoints" class="md-nav__link"> API Endpoints </a> </li> <li class="md-nav__item"> <a href="#how-to-use-the-authorization-service-api" class="md-nav__link"> How to use the Authorization Service API </a> </li> <li class="md-nav__item"> <a href="#querying-with-pagination" class="md-nav__link"> Querying with pagination </a> </li> <li class="md-nav__item"> <a href="#requesting-permissions" class="md-nav__link"> Requesting Permissions </a> </li> <li class="md-nav__item"> <a href="#querying-computed-fields" class="md-nav__link"> Querying computed fields </a> </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/authzsvc/overview.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 id="authorization-service-api">Authorization Service API</h1> <p>The <a href="https://authorization-service-api.web.cern.ch/swagger/index.html">Authorization Service API</a> is an OAuth2 protected API used by CERN's Identity Management Infrastructure to manage Identities, Groups, Roles, Applications and more. You may also want to use it, for example to:</p> <ul> <li>Query Groups</li> <li>Search for Identities</li> <li>Programmatically create Applications, and Roles</li> </ul> <h2 id="api-endpoints">API Endpoints</h2> <p>You can see all the available API endpoints, and test the Authorization Service API using the <a href="https://authorization-service-api.web.cern.ch/swagger/index.html">Swagger Interface</a> Through the API you can manage different resources such as identities, groups, accounts etc. For more details on the different resources and their attributes check <a href="../model/">here</a>.</p> <h2 id="how-to-use-the-authorization-service-api">How to use the Authorization Service API</h2> <p>For most needs we recommend creating an OIDC client and using your Client Credentials to query the Authorization Service, follow this <a href="../../user-documentation/oidc/api-access/">Guide for API Access</a>. If you want to query the Authorization Service on behalf of a user accessing your own application, i.e. OIDC delegation, follow this <a href="../../user-documentation/oidc/exchange-for-api/">Guide for Token Exchange</a>. The Authorization Service's clientID is <code>authorization-service-api</code>, which should be used as the <code>aud</code> or <code>audience</code> in your requests.</p> <p>Once you have an access token for the Authorization Service, you can include it in the Authorization header of an HTTP request to query the API:</p> <div class="highlight"><pre><span></span><code><span class="c1">### Call the Authorization Service API using your the exchanged token</span> <span class="nv">API_RESPONSE</span><span class="o">=</span><span class="k">$(</span>curl<span class="w"> </span><span class="se">\</span> <span class="w"> </span>-X<span class="w"> </span>GET<span class="w"> </span><span class="s2">"https://authorization-service-api.web.cern.ch/api/v1.0/Identity/my"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span>-H<span class="w"> </span><span class="s2">"Accept: */*"</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span>-H<span class="w"> </span><span class="s2">"Authorization: Bearer </span><span class="nv">$API_ACCESS_TOKEN</span><span class="s2">"</span><span class="w"> </span><span class="k">)</span> <span class="nb">echo</span><span class="w"> </span><span class="nv">$API_RESPONSE</span> </code></pre></div> <h2 id="querying-with-pagination">Querying with pagination</h2> <p>For the case that you need to query the API to receive back a big amount of entities you'll need to do it with pagination (receive them in chunks).</p> <p>For example let's assume one wants to get back all the groups. This means that they'll need to send a post request to the endpoint <code>https://authorization-service-api.web.cern.ch/api/v1.0/Group</code>.</p> <p>The response they'll receive will contain the following payload: <div class="highlight"><pre><span></span><code><span class="p">{</span> <span class="w"> </span><span class="nt">"pagination"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span> <span class="w"> </span><span class="nt">"total"</span><span class="p">:</span><span class="w"> </span><span class="mi">72272</span><span class="p">,</span> <span class="w"> </span><span class="nt">"offset"</span><span class="p">:</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span> <span class="w"> </span><span class="nt">"limit"</span><span class="p">:</span><span class="w"> </span><span class="mi">1000</span><span class="p">,</span> <span class="w"> </span><span class="nt">"next"</span><span class="p">:</span><span class="w"> </span><span class="s2">"/api/v1.0/Group?token=eyJJZCI6IjA4ZDc4&limit=1000"</span><span class="p">,</span> <span class="w"> </span><span class="nt">"links"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span> <span class="w"> </span><span class="nt">"first"</span><span class="p">:</span><span class="w"> </span><span class="s2">"/api/v1.0/Group?offset=0&limit=1000"</span><span class="p">,</span> <span class="w"> </span><span class="nt">"previous"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span> <span class="w"> </span><span class="nt">"current"</span><span class="p">:</span><span class="w"> </span><span class="s2">"/api/v1.0/Group?offset=0&limit=1000"</span><span class="p">,</span> <span class="w"> </span><span class="nt">"next"</span><span class="p">:</span><span class="w"> </span><span class="s2">"/api/v1.0/Group?offset=1000&limit=1000"</span><span class="p">,</span> <span class="w"> </span><span class="nt">"last"</span><span class="p">:</span><span class="w"> </span><span class="s2">"/api/v1.0/Group?offset=72000&limit=1000"</span> <span class="w"> </span><span class="p">},</span> <span class="w"> </span><span class="nt">"token"</span><span class="p">:</span><span class="w"> </span><span class="s2">"eyJJZCI6IjA4ZDc3OWE2LTE3YjYtOTAzNy01MzQzLTc4"</span> <span class="w"> </span><span class="p">},</span> <span class="w"> </span><span class="nt">"delta"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span> <span class="w"> </span><span class="nt">"request_id"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span> <span class="w"> </span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span> <span class="w"> </span><span class="nt">"data"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span> <span class="w"> </span><span class="p">{</span> <span class="w"> </span><span class="nt">"groupIdentifier"</span><span class="p">:</span><span class="w"> </span><span class="s2">"some group"</span><span class="w"> </span> <span class="w"> </span><span class="p">}</span><span class="w"> </span> <span class="w"> </span><span class="err">....</span> </code></pre></div></p> <p>The <code>pagination</code> field contains all the important information that you need.</p> <ol> <li>The field <code>limit</code> describes the number of groups contained in each page. By default it's <code>1000</code> but one can ask up to <code>5000</code> groups per page. If you want to set it to a different value you can define it in your initial request like this: <code>https://authorization-service-api.web.cern.ch/api/v1.0/Group?limit=500</code>.</li> <li>The field <code>total</code> describes the total amount of groups that are stored in the DB.</li> <li>The field <code>links</code> contains all the links to which the user should post another request to get the the next chunk of groups. In more detail:<ul> <li><code>next</code>: gives the user the next page of groups. If it's <code>null</code> it means there are no more pages to retrieve.</li> <li><code>previous</code>: gives the user the previous pages of groups. If it's <code>null</code> it means that the user is in the first page.</li> <li><code>current</code>: link to the current page.</li> <li><code>last</code>: last page of groups.</li> </ul> </li> </ol> <h2 id="requesting-permissions">Requesting Permissions</h2> <p>Due to privacy factors, certain endpoints require permission to query.<br /> See the <a href="../../applications/permission-scheme/">"defining the permissions scheme"</a> topic for more information.</p> <h2 id="querying-computed-fields">Querying computed fields</h2> <p>When making GET requests, for example, when reading an Identity, you will get a default object containing most of the available fields.</p> <p><code>GET https://authorization-service-api.web.cern.ch/api/v1.0/Identity/aaguadoc</code> <div class="highlight"><pre><span></span><code>{ "request_id": null, "message": null, "data": { "owner": null, "supervisor": null, "primaryAccountEmail": null, "type": "Person", "upn": "aaguadoc", "displayName": "Asier Aguado Corman", "personId": "806747", "supervisorId": "922d1465-59d5-4789-a468-58291c08c812", "source": "cern", "unconfirmed": false, "unconfirmedEmail": null, "externalEmail": "asieraguadoc@gmail.com", "primaryAccountId": "a8293927-4e84-4090-be61-0152381c7a9a", "uid": 96222, "gid": 2763, "resourceCategory": "Personal", "reassignable": false, "autoReassign": false, "blocked": false, "securityIssues": false, "blockingReason": null, "blockingTime": null, "blockingDeadline": null, "expirationDeadline": null, "ownerId": null, "id": "4499f2b8-2bcd-4d0a-bf81-73c119fb7bf9", "room": "003", "floor": "R", "building": "28", "lastName": "Aguado Corman", "birthDate": "1993-02-01T00:00:00", "cernGroup": "CDA", "firstName": "Asier", "activeUser": true, "telephone1": "65228", "cernSection": "IC", "description": "CERN - IT/CDA", "cernPersonId": "806747", "instituteName": "CERN", "cernDepartment": "IT", "eduPersonUniqueID": "4c84ca68be3a4010933b16caf1e030fe", "instituteAbbreviation": "CERN", "preferredCernLanguage": "EN" } } </code></pre></div></p> <p>You will probably notice that some fields in this default object are <code>null</code>. Some of the fields have an actual null value (e.g. <code>blockingDeadline</code> or <code>expirationDeadline</code>), but others are fields that belong to other child objects, which are not computed by default to make the API more efficient. If you need any of these fields, you can specify them in the request using the <code>field</code> parameter.</p> <p>For example, for getting <code>primaryAccountEmail</code>:</p> <p><code>https://authorization-service-api.web.cern.ch/api/v1.0/Identity/aaguadoc?field=primaryAccountEmail&field=upn</code></p> <div class="highlight"><pre><span></span><code>{ "request_id": null, "message": null, "data": { "primaryAccountEmail": "asier.aguado@cern.ch", "upn": "aaguadoc", "id": "4499f2b8-2bcd-4d0a-bf81-73c119fb7bf9" } } </code></pre></div> <p>As you can see in the example, when specifying fields in the request all the others are ignored in the response (even the default ones). If you also want to get them (e.g. <code>upn</code>) you can include them in your request as well.</p> </article> </div> </div> </main> <footer class="md-footer"> <nav class="md-footer__inner md-grid" aria-label="Footer" > <a href="../../services/instances/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Links to instances" 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> Links to instances </div> </div> </a> <a href="../managed-applications/" class="md-footer__link md-footer__link--next" aria-label="Next: Managing applications for other users" rel="next"> <div class="md-footer__title"> <div class="md-ellipsis"> <span class="md-footer__direction"> Next </span> Managing applications for other users </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>

CINXE.COM

Overview - Authentication and Authorization Service