Introduction
Authentication API는 Auth0을 사용할 때 user identity의 모든 측면을 관리할 수 있도록 해준다.
이것은 endpoints를 제공하여 user가 log in, sign up, log out, access APIs, 그리고 등등의 것들을 할 수 있도록 하게 한다.
Base URL
Authentication API는 HTTP 위에서 제공된다. 문서에 나타난 모든 URL은 base를 가진다 : setting에서 확인 가능한 링크
Authentication methods
이 API를 이용한 authenticating을 위한 5가지의 options
- OAuth2 Access Token
- Client ID and Client Assertion (confidential applications)
- Client ID and Client Secret (confidential applications)
- Client ID (public applications)
- mTLS Authentication (confidential applications)
OAuth2 Access Token
Bearer authentication scheme를 사용하여 Authorization header에 유효한 Access Token을 보낸다.
예시는 Get User Info endpoint이다. 이 시나리오에서, user를 인증할 때 Access Token을 얻을 수 있고 사용자의 프로필을 검색하기 위해 Authorization header에 있는 token을 사용해 Get User Info endpoint에 요청을 만들 수 있다.
Client ID and Client Assertion
인증을 위해 서명된 JSON Web Token (JWT)를 포함한 client assertion을 생성한다.
요청의 body에서, Client ID, 값이 urn:ietf:params:oauth:client-assertion-type:jwt-bearer인 client_assertion_type 매개변수, 그리고 서명된 assertion과 함께 client_assertion 매개변수를 포함한다.
Client ID and Client Secret
Client ID와 Client Secret을 보낸다. 이 data를 보낼 수 있는 method는 Token Endpoint Authentication Method에 설명되어 있다.
만약 Post를 사용한다면, request의 JSON body에 이 data를 반드시 보내야 한다.
만약 Basic을 사용한다면, Basic authentication scheme를 사용하여 Authorization header에 이 data를 반드시 보내야 한다. credential value를 생성하기 위해, Client ID와 Client Secret을 :로 구분하여 Base64로 encode 해야 한다.
예시는 Revoke Refresh Token endpoint이다. 이 option은 오직 credential applications에서만 사용 가능하다. (예를 들어 인증되지 않은 당사자에게 노출되지 않고 안전한 방식으로 자격 인증을 할 수 있는 applications)
Client ID
Client ID를 보낸다. SPAs 또는 mobile apps처럼, 자격 증명을 안전하게 보관하지 못하는)public applications를 위해, Client ID만을 사용하여 접근할 수 있는 몇몇의 endpoints를 제공한다.
mTLS Authentication
자체 서명 또는 인증기관 서명 인증서를 생성한다.
그러고 mTLS handshake를 수행하는 the customer edge network를 설정하라
일단 edge network가 인증서를 확인하면, Auth0 edge network로 가는 요청은 다음의 Header를 가진다:
- Custom Domain API key as the "cname-api-key" header
- The client certificate as the "client-certificate" header.
- The client certificate CA verification status as the "client-certificate-ca-verified" header.
Parameters
GET requests를 위해, path의 segment로 지정되지 않은 모든 매개변수는 HTTP query string parameter로 전달될 수 있다.
GET 'baseurl'POST requests를 위해, URL에 포함되어 있지 않은 parameter들은 Content-Type이 application/json인 JSON으로 인코딩되어야만 한다.
curl --request POST --url 'baseurl' -- header 'content-type: application/json' --data '{"param": "value", "param": "value"}'Errors
error가 발생했을 때, error 객체를 받게 될 것이다. error 객체의 대부분은 error code와 error 설명을 포함하여 효율적으로 문제를 찾을 수 있도록 한다.
만약 4xx HTTP response code를 받았다면, 내 end로부터 bad request가 있다고 추정할 수 있다.
5xx error들은 Auth0의 end에서 나타나는 문제를 제시한다.
Login
Social
GET /authorize
이 endpoint를 이용하여 social provider에게 user를 인증하라.
connection에 지정된 social provider에게 302를 return할 것이다.
Request Parameters
- response_type(required) : 서버 쪽 흐름에는 code를 사용하고 application 쪽 흐름에는 token을 사용
- client_id(required) : appliciation의 client_id
- connection : application에 구성된 socail identity procider로 예를 들어, google-oauth2 또는 facebook이다. 만약 null이면, Auth0 Login Page를 반환하고 Login Widget을 보여준다.
- redirect_uri(required) : 사용자에 의해 인증이 승인된 후 Auth0가 browser를 redirect할 URL이다.
- state(recommended) : applicaiton으로 redirecting할 때 인증 서버가 포함하는 초기의 요청에 application이 추가하는 불투명한 값. 이 값은 CSRF 공격을 예방하기 위해 application으로부터 반드시 사용되어야 한다.
- ADDITIONAL_PARAMETERS : 요청 끝에 추가 파라미터를 추가하면, 이것은 provider에게 보내진다. 예를 들어, access_type = offline(for Google Refresh Tokens), display = popup (for Windows Live Popup mode).
Remarks
redirect_url 값은 내 Applicaiton's Settings에 유효한 callback URl로서 지정된 값이어야 한다.
만약 response_type = token이라면, provider에서 user 인증 후에, 이것은 applicaiton callback URL로 Access Token과 address location.hash의 ID Token이 전달되면서 redirect 될 것이다.
Database/AD/LDAP (Passive)
GET /authorize
이 endpoint를 이용하여 social provider에게 user를 인증하라.
connection에 지정된 social provider에게 302를 return할 것이다.
Request Parameters
- response_type(required) : 서버 쪽 흐름에는 code를 사용하고 application 쪽 흐름에는 token을 사용
- client_id(required) : appliciation의 client_id
- connection : application에 구성된 connection의 이름. 만약 Null이라면, Auth0 Login page로 redirect 되고 first database connection을 이용해 Login Widget을 보여줄 것이다.
- redirect_uri(required) : 사용자에 의해 인증이 승인된 후 Auth0가 browser를 redirect할 URL이다.
- scope : OIDC scopes와 custom API scopes이다. 예를 들어, openid read:timesheets.
- state(recommended) : applicaiton으로 redirecting할 때 인증 서버가 포함하는 초기의 요청에 application이 추가하는 불투명한 값. 이 값은 CSRF 공격을 예방하기 위해 application으로부터 반드시 사용되어야 한다.
Remarks
redirect_url 값은 내 Applicaiton's Settings에 유효한 callback URl로서 지정된 값이어야 한다.
만약 response_type = token이라면, provider에서 user 인증 후에, 이것은 applicaiton callback URL로 Access Token과 address location.hash의 ID Token이 전달되면서 redirect 될 것이다.
passive authentication과 active authentication의 가장 주요 차이점은 전자는 Auth0 Login Page를 통하여 browser에서 일어난다는 것과 후자는 어느 곳에서나 불러일으킬 수 있다는 것이다.
