!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
"#$%&!'()!
*+,+-./+01!2$34+!
!
!
!
!
!
!
5367!84+6%3%9:!86;(!•!<))<!<=%&!>%0++%:!>$3%+!<)):!*+6,+0:!?"!@)') ' !•!A)A(BC@('D))!
! !
!
OAuth!2.0!Developers!Guide!
!
'!
!
Table&of&Contents!
Contents!
TABLE OF CONTENTS ............................................................................................................................ 2!
ABOUT THIS DOCUMENT ............................................................................................................................ 3!
GETTING STARTED ................................................................................................................................. 4!
1! OVERVIEW .......................................................................................................................................... 5!
1.1! OAUTH 2.0 OVERVIEW ..................................................................................................................... 5!
1.2! DEVELOPER CONSIDERATIONS ......................................................................................................... 5!
1.2.1! Application Developer ............................................................................................................... 5!
1.2.2! API Developer ........................................................................................................................... 6!
APPLICATION DEVELOPER CONSIDERATIONS ............................................................................ 7!
2! GET A TOKEN ..................................................................................................................................... 8!
2.1! OAUTH 2.0 GRANT TYPES ................................................................................................................ 8!
2.2! AUTHORIZATION CODE GRANT ........................................................................................................ 9!
2.2.1! Client Configuration ................................................................................................................ 10!
2.2.2! Request authorization from user and retrieve authorization code .......................................... 10!
2.2.3! Swap the authorization code for an access token .................................................................... 11!
2.3! IMPLICIT GRANT ............................................................................................................................. 13!
2.3.1! Client Configuration ................................................................................................................ 14!
2.3.2! Request authorization from user and retrieve access token .................................................... 14!
2.4! RESOURCE OWNER PASSWORD CREDENTIALS (ROPC) ................................................................ 16!
2.4.1! Client Configuration ................................................................................................................ 16!
2.4.2! Request user authentication and retrieve access token ........................................................... 17!
2.5! CLIENT CREDENTIALS .................................................................................................................... 19!
2.5.1! Client Configuration ................................................................................................................ 19!
2.5.2! Request access token ............................................................................................................... 20!
2.6! EXTENSION GRANTS (I.E. SAML BEARER) ..................................................................................... 21!
2.6.1! Client Configuration ................................................................................................................ 21!
2.6.2! Request access token ............................................................................................................... 22!
3! REFRESH A TOKEN ......................................................................................................................... 24!
4! USE A TOKEN .................................................................................................................................... 26!
API DEVELOPER CONSIDERATIONS ............................................................................................... 27!
5! VALIDATE A TOKEN ....................................................................................................................... 28!
5.1.1! Client Configuration ................................................................................................................ 28!
6! REFERENCES .................................................................................................................................... 31!
!
!
!
OAuth!2.0!Developers!Guide!
!
A!
!
About!this!Document!
!
E&31!4.;$F+6%! /0.,34+1!G! 4+,+-./+0!.,+0,3+H! .I! %&+! "#$%&! '()!/0.%.;.-(!! 8%! /0.,34+1!G6! .,+0,3+H!.I! %&+!
/0.;+11+1!G6!G//-3;G%3.6!4+,+-./+0!G64!G6!#58! 4+,+-./+0!6++4!%.!;.6134+0!%.!3F/-+F+6%!%&+! "#$%&!'()!
/0.%.;.-(!
!
JK/-G6G%3.61! G64! ;.4+! +KGF/-+1! G0+! /0.,34+4 ! I.0! LM$3;N! H36L! 36%+70G%3.6! +II.0%1(! ! #1! 1$;&:! %&+9! G0+!
36;.F/ -+ %+ !G 6 4 !F + G 6 %!%. !; . F / -+ F+6%!+K31% 36 7!4 . ; $F+6%G%3. 6 !G 6 4!1 / + ;3I3; G %3. 6 1( !
!
E&31! 4.;$F+6%! G11$F+1! IGF 3-3G03%9! H3%&! %&+! "#$%&! '()! /0.%.;.-! G64! 5367O+4+0G%+(! ! O.0! F .0 +!
36I.0FG %3. 6 !G P . $% !" # $ %& !' () :!0+ I+ 0!%. Q!
!
• 5367O+4+0G%+!#4F3631%0G%.0R1!SG6$G-!
• "#$%&!'()!TO?!C=BD!
E&+! 1GF/-+1! 4+1;03P+4! 36! %&31! 4.;$F +6%! $1+! %&+! "#$ %&'! 5-G970.$64! 1GF/-+! G//-3;G%3.6! G,G3-GP-+! I.0!
4.H6-.G4!I0.F!%&+!/0.4$;%1!/G7+!.6!/36734+6%3%9(;.F(!
!
!
U.%+Q! E&31!4.;$F+6%!+K/-G361!G!6$FP+0!.I!FG6$G-!/0.;+11+1!%.!0+M$+1%!G64! ,G-34G%+!%&+!"#$%&!
%.N+61(! V&3-+!%&+!36%+0G;%3.61!G0+!13F/-+:!5367O+4+0G%+!31!;.F/G%3P-+!H3%&!FG69!A
04
! /G0%9!
"#$%&!;-3+6%!-3P0G03+1!%&G%!FG 9!13F/-3I9!4+,+-./F+6%!+II.0%(!
!
!
!
OAuth!2.0!Developers!Guide!
!
B!
!
Getting'Started!
!
!
OAuth!2.0!Developers!Guide!
!
W!
!
1 Overview!
!
1.1 OAuth!2.0!Overview!
!
!
E&+!"#$%&! '()!/0.%.;.-!$1+1! G! 6$FP+0! .I! G;%.01!%.!G;&3+,+! %&+! F G36! %G1N1! .I! 7+%%367:!,G-34G%367:!G64!
$1367!G6!G;;+11!%.N+6(!E&+1+!H3--!P+!4+1;03P+4:!G1!H+--!G1!./%3.6G-!1%+/1!.I!0+I0+1&367!%&31!G;;+ 11!%.N+ 6(!
!
E&+!FG36!G;%.01!36,.-,+4!G0+Q!
!
Actor!
Responsibility!
X1+0!.0!T+1.$0;+!"H6+0!
E&+!G;%$G-! +64!$1+0:!0+1/.613P-+! I.0!G$%&+6%3;G%3.6!G64! %.!/0.,34+!;.61+6%!%.! 1&G0+!
%&+30!0+1.$0;+1!H3%&!%&+!0+M$+1%367!;-3+6%(!
X1+0!#7+6%!
E&+! $1+0Y1! P0.H1+0(! ! X1+4! I.0! 0+430+;%ZPG1+4! I-.H1! H &+0+! %&+! $1+0! F$1%!
G$%&+6%3;G%+!G64!./%3.6G--9!/0.,34+!;.61+6%!%.!1&G0+!%&+30!0+1.$0;+1(!
?-3+6%!
E&+!;-3+6%!G//-3;G%3.6!%&G%!31!0+M$+1%367!G6!G;;+11!%.N+6!.6!P+&G-I!.I!%&+!+64!$1+0(!
#$%&.03[G%3.6!>+0,+0!\#>]!
E&+! 5367O+4+0G%+! 1+0,+0! %&G%! G$%&+6%3;G%+1! %&+! $1+0! G64^.0! ;-3+6%:! 311$+1! G;;+11!
%.N+61!G64!%0G;N1!%&+!G;; +11!%.N +61 !%&0.$ 7&. $%!%& +30!-3I+%3F+ ( !
T+1.$0;+!>+0,+0!\T>]!
E&+!%G07+%! G/ /-3;G%3.6!.0!#58!%&G%!/0.,34+1!%&+!0+M$+1%+4!0+1.$0;+1(!!E&31! G;%.0!H3--!
,G-34G%+!G6!G;;+11!%.N+6!%.!/0.,34+!G$%&.03[G%3.6!I.0!%&+!G;%3.6(!
!
!
1.2 Developer!Considerations!
1.2.1 Application!Developer!
!
E&+! G//-3;G%3.6! 4+,+-./+0! H3--! P+! 0+1/.613P-+! I.0! %&+! $1+0ZIG;367! +-+F+6%1 ! .I! %&+! /0.;+ 11(! ! E&+9! H3--!
6++4!%.!G$%&+6%3;G%+!%&+!$1+0!G64!36%+0IG;+!H3%&!%&+!PG;NZ+64!#581(!
Protected API
Authorization Server
Resource Server
Client
User User Agent
!
OAuth!2.0!Developers!Guide!
!
C!
!
!
E&+0+!G0+!%&0++!FG36!G;%3.61!G6!G//-3;G%3.6!4+,+-./+0!6++41!%.!&G64-+!%.!3F/-+F+6%!"#$%&!'()Q!
!
<( 2+%!G6!G;;+11!%.N+6!
'( X1+!G6!G;;+11!%.N+6!
A( T+I0+1&!G6!G;;+11!%.N+6!\./%3.6G -]!
1.2.2 API!Developer!
!
E&+! #58! 4+,+-./+0! P$3-41! %&+! #58! %&G%! %&+! G//-3;G%3.6! %G-N1! %.(! ! E&31! 4+,+-./+0! 31! ;.6;+06+4! H3%&! %&+!
/0.%+;%3.6!.I!%&+!#58!;G--1!FG4+!G64!4+%+0F36367!H&+%&+0!G!$1+0!31!G$%&.03[+4!%.!FGN+!G!1/+;3I3;!#58!
;G--(!
!
E&+!"#$%&!'()!/0.;+11!G6!#58!4+,+-./+0!6++41!%.!&G64-+!31!%.Q!
!
<( _G-34G%+!G!%.N+6!
U.%+Q! 86!1. F+!; G1 + 1!%&+!`#58!*+,+-./+0a!FG9!P+!$1367!G!1+0,3;+!P$1!.0!G$%&.03[G%3.6!7G%+HG9!%.!
FG6G7+! G;;+11! %.! #581:! G64! %&+0+I.0+! %&+! %G1N! .I! ,G-34G%367! %&+! G;;+11! %.N+6! H.$ -4! P+ !
1&3I%+4!%.!%&31!36I0G1%0$;%$0+(!
!
!
!
!
!
!
OAuth!2.0!Developers!Guide!
!
=!
!
Application*Developer*Considerations!
!
!
!
!
!
OAuth!2.0!Developers!Guide!
!
@!
!
2 Get$a$token!
!
E&31!1+;%3.6!H3--!+K/-G36!&.H!%.!7+%!G6!"#$%&'!G;;+11!%.N+6!\G64!./%3.6G--9!G!0+I0+1&!%.N+6]!I0.F!%&+!
5367O+4+0G%+!36I0G1%0$;%$0+(!
!
2.1 OAuth!2.0!Grant!Types!
!
"#$%&!'()!/0.,34+1!I.$0!1%G64G04!70G6%!%9/+1!G64!G6!+K%+613.6!70G6%!%9/+!%&G%!;G6!P+!$1+4! %.!;$1%.F 3[+!
%&+!G$%&+6%3;G %3.6 !G64!G$%&.03[G%3.6!/0.;+11!4+/+64367!.6!%&+!G//-3;G%3.6!0+M$30+F+6%1(!
!
Use!Cases!
X1+4!I.0!F.1%!H +P!G64!F.P3-+!G//-3;G%3.6!1;+6G03.1!%&G%!HG6%!%.!;G--!
TJ>E!H+P!1+0,3;+1(!
X1+1!%&+!$1+0! G7+6%!%.!%0G61/.0%!G6!36%+0F+43G%+!;.4+:! H&3;&!31! %&+6!
+K;&G67+4!I.0!%&+!"#$%&'!%.N+61(!
>;+6G03.! H&+0+! ;-3+6%! 31! 6.%! GP-+! %.! 1GI+-9! &34+! %&+! ;-3+6%! 1+;0+%! \+(7(!
;-3+6%134+!bG,G>;03/%!G//-3; G %3. 6](!
X1+1!%&+!$1+0!G7+6%!%.!%0G61/.0%!%&+!"#$%&'!%.N+61(!
V&+6!G//-3;G%3.6!6++41! %.! ;.6%0.-! %&+!-.736! I.0F! \ +(7(! 6G %3, +! F . P 3-+!
G//](!!
JK;&G67+1!G!$1+06GF+^/G11H.04!;.FP36G%3.6!I.0!%&+!"#$%&'!%.N+61(!
V&+6!G!$1+0!31!6.%!36,.-,+4(!!#;;+11!%.N+6!.6-9!0+M$30+4!I.0!G!1+0,3;+!%.!
;G--!G!TJ>E!H+P!1+0,3;+(!
JK;&G67+1!%&+!;-3+6%!;0+4+6%3G-1!I.0!G6!"#$%&'!G;;+11!%.N+6(!
X1+4! %.! +K%+64! %&+! "#$%&! '()! 70G6%! %9/+1! I. 0! 1/+;3I3;! 1;+6 G03. 1! \+(7(!
%&+!>#Sc!P+G0+0!+K%+613.6!70G6%](!
!
!
!
! !
!
OAuth!2.0!Developers!Guide!
!
D!
!
2.2 Authorization!Code!Grant!
!
#$%&.03[G%3.6!70G6%!31!G!;-3+6%!0+430+;%!PG1+4!I-.H(!! 86!%&31!1;+6G03.:!%&+!$1+0! H 3--! P+ ! 0+ 430+; %+4! %.!%&+!
5367O+4+0G%+!G$%&.03[G%3.6!+64/.36%! ,3G!%&+!$1+0!G7+6%!\3(+(!H +P !P 0.H 1+ 0](!!E&31!$1+ 0!G7+6%!H 3--!P+!$1+4!
%.!G$%&+ 6%3;G %+!%&+!+64!$1+0!G64!G--.H!%&+F !%.!70G6%!G ;;+1 1!%.!%&+!;-3+6%!\>%+/!<!P +-. H ](!" 6 ;+!%&+!$1+0!
&G1!P++6!G$%&.03[+4:!G6!36% +0F+43G%+ !;. 4 + !H 3--!P + !70G 6 %+ 4 !P 9!% & +!G $ %& . 03[ G% 3. 6!1 + 0,+ 0!G 6 4 !0+ %$ 06 + 4!% . !
%&+! ;-3+6%! G//-3;G%3.6! ,3G! %& +! $1+0! G7+6%! \1 %+/! '](! ! cG1%-9:! %&+ ! ;-3+6%! H 3--! 1HG/! %&31! ;.4+ ! I.0! G6 ! "#$%&!
G;;+11!%.N+6!\1%+/!A](!
!
!
!
!
!
!
Capability!
!
d0.H1+0ZPG1+4!+64!$1+0!36%+0G;%3.6!
e+1!
?G6!$1+!+K%+06G-!8*5!I.0!G$%&+6%3;G%3.6 !
e+1!
T+M$30+1!;-3+6%!G$%&+6%3;G%3.6!
U.f!
T+M$30+1!;-3+6%!%.!&G,+!N6.H-+47+!.I!$1+0!;0+4+6%3G-1!
U.!
T+I0+1&!%.N+6!G--.H+4!
e+1!
#;;+11!%.N+6!31!36!;.6%+K%!.I!+64!$1+0!
e+1!
!
!
U.%+Q! #-%&.$7&!%&+!G$%&.03[G%3.6!;.4+!70G6%!%9/+ !4.+1!6.%!0+M$30+!G !;-3+6%!1+;0+%!,G-$+:!%&+0+!G0+!
1+;$03%9!3F/-3;G%3.61!%.!+K;&G67367!G!;.4+!I.0!G6!G;;+11!%.N+6!H3%&.$%!;-3+6%!G$%&+6%3;G%3.6(!
!
Protected API
Authorization Server
Resource Server
Client
User
Allow?
3
12
2
!
OAuth!2.0!Developers!Guide!
!
<)!
!
2.2.1 Client!Configuration!
!
O.0!%&+!+KGF/-+1!P+-.H:!%&+!I.--.H367!;-3+6%!36I.0FG%3.6!H3--!P+!$1+4Q!
!
Admin!Label!
OAuth2!Parameter!
Example!Value!
?-3+6%!8*!
;-3+6%g34!
G;g;-3+6%!
?-3+6%!#$%&+6%3;G%3.6!
;-3+6%g/G11H.04!
'O+4+0G%+!
#--.H+4!20G6%!E9/+1!
0+1/.61+g%9/ +!
70G6%g%9/+!
#$%&.03[G%3.6!?.4+!
• 0+1/.61+g%9/ +!.I!`; .4 +a!
• 70G6%g%9/+!.I!`G$%&.03[G%3.6g;.4+a!
T+I0+1&!E.N+6!
T+430+;%!XT81!
0+430+;%g$03!
1GF/-+Q^^.G$%&'^;.4+^;P!
>;./+!>+%%3671!\36!#>!
1+%%3671]!^!!
T+1%03;%!>;./+1!
1;./+!
+43%!
!
2.2.2 Request!authorization!from!user!and!retrieve!authorization!code!
!
E.!363%3G%+!%&+!/0.;+11:!%&+!;-3+6%!G//-3;G%3.6!H3--!0+430+;%!%&+!$1+0!%.!%&+!G$%&.03[G%3.6!+64/.36%(!!E&31!
0+430+;%!H3--!;. 6%G36 !%&+!G//-3; GP -+ !G%%03P$ % +1 !XTc !+6;.4+4!G64!36;-$4+4!36!%&+!M$+09!1%0367!;. F /.6 +6%!
.I!%&+!XTc(!
!
X1367!%&+!GP.,+!/G0GF+%+01!G1!G6!+KGF/-+:!%&+!G//-3;G%3.6!H3--!0+430+;%!%&+!$1+0!%.!%&+!I.--.H367!XTcQ!
!
https://localhost:9031/as/authorization.oauth2?
client_id=ac_client&
response_type=code&
scope=edit&
redirect_uri=sample%3A%2F%2Foauth2%2Fcode%2Fcb
!
!
E&31!H3--!363%3G%+!G6!G$%&+6%3;G%3.6!/0.;+11!$1367!%&+!P0.H1+0!\$1+0!G7+6%](!!"6;+!%&+!$1+0!1$;;+11I$--9!
;.F/-+%+1! %&+! G$%&.03[G%3.6! 0+M$+1%:! %&+9! H3--! P+! 0+430+;%+4! H3%&! G6! G$%&.03[G%3.6! ;. 4+! %.! %&+!
0+430+;%g$03!,G-$+!4+ I36+ 4!36!%&+!G$%& . 03[G%3.6 !0+M$ +1%!\3I!36;-$4 +4 ]!.%&+0H 31+ !%&+!$1+0!H 3--!P+!0+%$06+ 4!
%.!%&+!0+430+;%g$ 03!4+I36+ 4!H&+6!%&+!;-3+6%!HG1!;.6I37$0+4(!
!
U.%+Q! O.0!F.P3-+!1;+6G03.1:!%&+!0+430+;%g$03!FG9!P+!G! ;$1%.F! XTc!1;&+F+!%& G%!H3--!;G$1+!%&+!;.4+!
%.!P+!0+%$06+4 !%.!%&+ !6G%3,+ !G/ /-3;G%3. 6(!
!
!
X1367!%&+!+KGF/-+!GP.,+:!G!1$;;+11I$-!G$%&.03[G%3.6!0+M$+1%!H3--!0+1$-%!36!%&+!0+1.$0;+!.H6+0!0+430+;%+4!
%.!%&+!I.--.H 367!X Tc!H 3%&!%& +!G$ %&. 03[G%3.6 !;. 4+ !36;-$4 +4 !G1!G!`;. 4+ a!M$ +09!1%0367!/G0GF+%+0Q!
!
!
OAuth!2.0!Developers!Guide!
!
<<!
!
sample://oauth2/code/cb?code=XYZ…123
!
U.%+Q! 8I!%&+!G$%&.03[G %3. 6 !0+M $ +1 %!G-1. !36;-$ 4 +4!G!`1%G%+a!,G-$+:!%&31!H3--!G-1.!P+!36;-$4 + 4 !.6!%&31!
;G--PG;N(!
!
U.%+Q! #6!+00.0!;.643%3.6!I0.F!%&+!G$%&+6%3;G%3.6!^!G$%&.03[G%3.6!/0.;+11!H3--!P+!0+%$06+4!%.!%&31!
;G--PG;N!XT8!H3%&!`+00.0a!G64!`+00.0g4+1;03/%3.6a!/G0GF+%+01(!
!
E&+! ;-3+6%!H3--!%&+6!+K%0G;%! %&+!;.4+!,G-$+!I0.F!%&+! 0+1/.61+!G64:!./%3.6G--9:! ,+03I9!%&G%!%&+ !1%G%+!,G-$+!
FG%;&+1!%&+!,G-$+!/0.,34+4!36!%&+!G$%&.03[G%3.6!0+M$+1%(!
!
2.2.3 Swap!the!authorization!code!for!an!access!token!
!
E&+!I36G-! 1%+/! I.0! %&+!;-3+6%!31! %.! 1H G/! %&+!G$%&.03[G%3.6!;.4+! 0+;+3,+4! 36! %&+ !/0+,3.$ 1!1%+/!I. 0!G6!G;;+1 1!
%.N+6!%&G%!;G6!P+!$1+4! %.!G$%&.03[+!G;;+11! %.!0+1.$0;+1(! d9!-3F3%367!%&+!+K/.1$0+! .I! %&+!G;;+11! %.N+6! %.!
G! 430+;%! h EE5>! ;.66+;%3.6! P+%H++6! %&+!;-3+6%! G//-3;G%3.6! G64! %&+! G$%&.03[G%3.6! +64/. 36%:! %&+! 031N! .I!
+K/.1367!%&31!G;;+11!%.N+6!%.!G6!$6G$%&.03[+4!/G0%9!31!0+4$;+4(!
!
O.0!%&31!%.!.;;$0:!%&+!;-3+6%!FGN+1!G!hEE5!5">E!0+M$+1%!%.!%&+!%.N+6!+64/.36%!.6!%&+!#>(!!E&31!0+M$+1%!
H3--!$1+!%&+!I.--.H367!/G0GF+%+ 01!1+6 %!36!%&+!P.49!.I!%&+!0+M$+1%Q!
!
Item!
Description!
70G6%g%9/+!
T+M$30+4!%.!P+!`G$%&.03[G%3.6g;.4+a!
;.4+!
E&+!G$%&.03[G%3.6!;.4+!0+;+3,+4!36!%& +!/0+ ,3.$ 1!1%+/ !
0+430+;%g$03!
8I!%&31!HG1!36 ; -$ 4 + 4 !36 !%&+!G$ %&. 03[G%3.6 !0+M$ +1%:! 3%!SX>E!G-1.!P + !36 ; -$4 + 4!
!
E&31! 0+M$+1%! 1&.$-4! G-1.! G$%&+6%3;G%+! G1! %&+! /0+Z;.6I37$0+4! ;-3+6%! $1367! +3%&+0! hEE5! d#>8?!
G$%&+6%3;G%3.6!.0!P9!36;-$4367!%&+!;-3+6%g34!G64!;-3+6%g1+;0+%!,G-$+1!36!%&+!0+M$+1%(!
!
E.!0+%03+,+!%&+!G;;+11!%.N+6!36!%&+!+KGF/-+:!%&+!I.--.H367!0+M$+1%!H3--!P+!FG4+(!
!
hEE5!T+M$+1%!
POST https://localhost:9031/as/token.oauth2 HTTP/1.1!
h+G4+01!
Content-Type:
Authorization:
application/x-www-form-urlencoded
Basic YWNfY2xpZW50OjJGZWRlcmF0ZQ==
d.49!
grant_type=authorization_code&code=XYZ…123
!
#!1$;;+11I$-!0+1/.61+!%.!%&31!F+11G7+!H3--!0+1$-%!36!G!'))!"i!hEE5!0+1/.61+!G64!%&+!G;;+11!%.N+6!\G64!
./%3.6G-!0+I0+1&!%.N+6]!0+%$06+4!36!G!b>"U!1%0$ ;%$0+ !36!%&+ !P.4 9!.I!%& +!0+1/ . 61+( !
!
!
OAuth!2.0!Developers!Guide!
!
<'!
!
hEE5!T+1/.61+!
HTTP/1.1 200 OK!
h+G4+01!
Content-Type:
application/json;charset=UTF-8
d.49!
{
"access_token":"zzz…yyy",
"token_type":"Bearer",
"expires_in":14400,
"refresh_token":"123…789"
}
!
E&+! G//-3;G%3.6! ;G6! 6.H! /G01+! %&+! G;;+11! %.N+6 ! G 64 :! 3I! /0+ 1+ 6%:! %&+! 0+I0+1&! %.N+6 ! %. ! $ 1+! I.0!
G$%&.03[G%3.6!%.!0+1.$ 0;+ 1(!!8I!G !0+ I0+1& !%. N+ 6!H G 1!0+ %$06 +4 :!3%!; G6 !P +!$ 1+ 4!%. !0+ I0+1& !G;;+11!%.N+ 6!.6;+!
3%!+K/30+1(!
!
!
! !
!
OAuth!2.0!Developers!Guide!
!
<A!
!
2.3 Implicit!Grant!
!
E&+!3F/-3;3%!70G6%!31!13F3-G0!%.!G6!G$%&.03[G%3.6!;.4+!70G6%:!&.H+,+0!%&+!$1+0!G7+6%!H3--!0+;+3,+!G6!G;;+11!
%.N+6!430+;%-9!I0.F !G6 !G$ %&. 03[G%3.6 !0+M$ +1 %!\0G%&+ 0!%&G6 !1HG// 367!G6!36% +0F+43G%+ !G$ %& . 03[ G %3. 6 !;. 4 + ](!
!
86! %&31! I-.H:! %&+! $1+ 0! 0+ M $ + 1% 1! G $ %& + 6 % 3;G %3.6! G 6 4! G $ %& . 03[ G% 3. 6! , 3G! % & +! $ 1+ 0! G 7 +6 % ! \1%+ / ! <! P + -.H](! ! 8I!
G$%&.03[+4:!%&+!G$ %&.03[G%3.6! 1+0,+0!H3--!0+430+;%!%&+!$1+0!%.!G!XT c!;.6%G36367!%&+!G;;+11!%.N+6!36!G!XTc!
I0G7F+6%(! ! E&+! ;-3+6 %! ;G6! %&+6! / G01 +! %&31! I0.F! %&+! XTc! \1%+/! ']! %. ! $ 1+! I.0! 0+M$+1 %1! %. ! / 0.%+;%+4!
0+1.$0;+1(!
!
!
!
E&31!70G6%!%9/+!31!1$3%GP-+!I.0!;-3+6%1!%&G%!G0+!$6GP-+!%.!N++/!G!1+;0+%!\3(+(!;-3+6%Z134+!G//-3;G%3.61! -3N+!
bG,G>;03/%](!!E & +!;-3+6%!31!`FG// +4 a !%.!%&+!G$%&.03[G% 3.6 !1+0,+0 !,3G!%&+!0+430+;%g$ 03:!G1!%&+0+!31!6. !;-3+6%!
1+;0+%!%. !G$%&+6%3;G%+!%&+!;-3+6%:!%&+!G;;+11! %.N+6! H 3--! P+!1+6%! %.!G! 1/+;3I3;! XTc!/0+Z6+7.%3G%+4!P+%H++6!
%&+!;-3+6%!G64!%&+ !G$%& .03[G %3.6 !1+0,+ 0(!
!
#1! %&+! G;;+11! %.N+6! 31! /0.,34+4! %.! %&+! ;-3+6%! 36! %&+! 0+M$+1%! XT8:! 3%! 31! 36&+0+6%-9! -+11! 1+;$0+! %&G6! %&+!
G$%&.03[G%3.6!;.4+!70G6%!%9/+(!!O.0!%&31!0+G1.6:!G6!3F/-3;3%!70G6%!%9/+!;G66.%!%GN+!G4,G6%G7+!.I!0+I0+1&!
%.N+61(!!"6-9!G;; +11!%. N+6 1!;G6 !P+ !/0., 34+4 !,3G!%&31!70G 6%!%9/ +(!
!
!
!
!
!
Protected API
Authorization Server
Resource Server
Client
User
Allow?
12
2
!
OAuth!2.0!Developers!Guide!
!
<B!
!
Capability!
!
d0.H1+0ZPG1+4!+64!$1+0!36%+0G;%3.6!
e+1!
?G6!$1+!+K%+06G-!8*5!I.0!G$%&+6%3;G%3.6 !
e+1!
T+M$30+1!;-3+6%!G$%&+6%3;G%3.6!
U.!
T+M$30+1!;-3+6%!%.!&G,+!N6.H-+47+!.I!$1+0!;0+4+6%3G-1!
U.!
T+I0+1&!%.N+6!G--.H+4!
U.!
#;;+11!%.N+6!31!36!;.6%+K%!.I!+64!$1+0!
e+1!
!
2.3.1 Client!Configuration!
!
O.0!%&+!+KGF/-+1!P+-.H:!%&+!I.--.H367!;-3+6%!36I.0FG%3.6!H3--!P+!$1+4Q!
!
Admin!Label!
OAuth2!Parameter!
Example!Value!
?-3+6%!8*!
;-3+6%g34!
3Fg;-3+6%!
?-3+6%!#$%&+6%3;G%3.6!
;-3+6%g/G11H.04!
U.6+!
#--.H+4!20G6%!E9/+1!
0+1/.61+g%9/ +!
8F/-3;3%!
• 0+1/.61+g%9/ +!.I!`%.N +6 a!
T+430+;%!XT81!
0+430+;%g$03!
1GF/-+Q^^.G$%&'^3F/ -3; 3%^;P!
>;./+!>+%%3671!\36!#>!
1+%%3671]!^!!
T+1%03;%!>;./+1!
1;./+!
+43%!
!
2.3.2 Request!authorization!from!user!and!retrieve!access!token!
!
E.!363%3G%+!%&+!/0.;+11:!%&+!;-3+6%!G//-3;G%3.6!H3--!0+430+;%!%&+!$1+0!%.!%&+!G$%&.03[G%3.6!+64/.36%(!!E&31!
0+430+;%!H3--!;. 6%G 36!%&+!G//-3;GP-+!G%%03P$%+1!XTc!+6;.4+4!G64!36;-$4+4!36!%&+!M$+09!1%0367!;.F/. 6+6 %!
.I!%&+!XTc(!
!
X1367!%&+!GP.,+!/G0GF+%+01!G1!G6!+KGF/-+:!%&+!G//-3;G%3.6!H3--!0+430+;%!%&+!$1+0!%.!%&+!I.--.H367!XTcQ!
!
https://localhost:9031/as/authorization.oauth2?
client_id=im_client&
response_type=token&
scope=edit&
redirect_uri=sample%3A%2F%2Foauth2%2Fimplicit%2Fcb
!
!
!
!
OAuth!2.0!Developers!Guide!
!
<W!
!
E&31! H3--! 363%3G%+! G6! G$%&+6%3;G%3.6! /0.;+11! $1367! %&+! P0.H1+0! \$1+0! G7+6%](! ! "6;+! %&+! $1+0! &G1!
G$%&+6%3;G%+4! G64! G//0.,+4! %&+! G$%&.03[G%3.6! 0+M$+1%:! %&+9! H 3--! P+! 0+430+;%+4! %.! %&+! ;.6I37$0+4! X T 8!
H3%&!%&+!G;;+11!%.N+6!36;-$4+4!G1!G!I0G7F+6%!.I!%&+!XTc(!#!0+I0+1&!%.N+6!H3--!U"E!P+!0+%$06+4!%.!%&+!
;-3+6%Q!
!
sample://oauth2/implicit/cb#
access_token=zzz...yyy&
token_type=bearer&
expires_in=14400
!
U.%+Q! O.0!F.P3-+!1;+6G03.1:!%&+!0+430+;%g$03!FG9!P+!G!;$1%.F!XTc!1;&+F+:!H&3;&!H3--!;G$1+!%&+!
G;;+11!%.N+6!%.!P+ !0+%$06 +4 !%.!%&+ !6G %3,+!G/ /-3;G%3. 6(!
!
!
U.%+Q! E&+! 3F/-3;3%! 0+1/.61+! 31! 0+%$06+4! ,3G! G! XTc! I0G7F+6%(! ! E&+! I0G7F+6%! 31! .6-9! ,313P-+! I0.F!
;-3+6%Z134+! ;. 4+(!!E&+0+I.0+!3I!9.$!6++4!%.!/ G01+!%&+!,G-$+1!I0.F!1+0,+0Z134+! ;.4 +:!9.$!F $1%!
/.1%!%&+!,G-$+1!%.!%&+!1+0,+0!I.0!/G01367(!
!
E&+!G//-3;G%3.6!;G6!6.H!/G01+!%&+!G;;+11!%.N+6!I0.F!%&+!XT c!I0G7F + 6%!%. !$1+!I. 0!G$%& .03[G %3.6 !%.!#5 8Y1(!
!
! !
!
OAuth!2.0!Developers!Guide!
!
<C!
!
2.4 Resource!Owner!Password!Credentials!(ROPC)!
!
E&+!T"5?!70G6%!%9/+!;G6!P +!$1+4!36!1;+6G03.1!H&+0+!G6!36%+0G;%3,+!$1+0!G7+6%!31!6.%!G,G3-GP-+:!H&+0+!
1/+;3I3;! 4+1376! 0+M$30+F +6%1! HG00G6 %! %&+! $1+! .I! G! 6G%3,+! G//-3;G%3.6! -. 7 36 ! 36% +0 IG; + :! . 0! I.0! -+7G;9 !
0+G1.61!\3(+(!0+%0. Z I3%%36 7!G!-.736!I.0F!I.0!"# $ %&' ](!!86!%& +!T"5 ? !70G6%!%9/+:!%&+!;-3+6%!;G/%$0+1!%&+!$1+0!
;0+4+6%3G-1!\1%+/!<!P+-.H ] !G64!$1+1!%&.1+!;0+4+6%3G-1!%.!1HG/!I.0!G6!G;;+11!%.N+6!\1%+/!'](!
!
!
!
!
Capability!
!
d0.H1+0ZPG1+4!+64!$1+0!36%+0G;%3.6!
U.!
?G6!$1+!+K%+06G-!8*5!I.0!G$%&+6%3;G%3.6 !
U.!
T+M$30+1!;-3+6%!G$%&+6%3;G%3.6!
U.!
T+M$30+1!;-3+6%!%.!&G,+!N6.H-+47+!.I!$1+0!;0+4+6%3G-1!
e+1!
T+I0+1&!%.N+6!G--.H+4!
e+1!
#;;+11!%.N+6!31!36!;.6%+K%!.I!+64!$1+0!
e+1!
2.4.1 Client!Configuration!
!
O.0!%&+!+KGF/-+1!P+-.H:!%&+!I.--.H367!;-3+6%!36I.0FG%3.6!H3--!P+!$1+4Q!
!
Protected API
Authorization Server
Resource Server
Client
User
1
2
!
OAuth!2.0!Developers!Guide!
!
<=!
!
Admin!Label!
OAuth2!Parameter!
Example!Value!
?-3+6%!8*!
;-3+6%g34!
0.g;-3+6%!
?-3+6%!#$%&+6%3;G%3.6!
;-3+6%g/G11H.04!
'O+4+0G%+!
#--.H+4!20G6%!E9/+1!
70G6%g%9/+!
T+1.$0;+!"H6+0!5G11H.04!?0+4+6%3G-1!
• 70G6%g%9/+!.I!`/G11H.04a!
T+I0+1&!E.N+6!
>;./+!>+%%3671!\36!#>!
1+%%3671]!^!!
T+1%03;%!>;./+1!
1;./+!
+43%!
!
2.4.2 Request!user!authentication!and!retrieve!access!token!
!
#%! %&31! 1%G7+:! %&+! ;-3+6%! 431/-G91! G! -.736! I.0F! %.! %&+! $1+0! G64! ;.--+;%1! %&+! ;0+4+6%3G-1! \+(7(!
$1+06GF+^/G11H.04]!G64!4+I36+4!1;./+!3I!0+M$30+4!I0.F!%&+!0+1.$0;+!.H6+0!\$1+0]!G64!FGN+1!G!hEE5!
5">E!%.!%&+!%.N+6!+64/.36%(!!!
!
O.0!%&+! +KGF/-+! P+-.H:! %&+!I.--.H367!;0+4+6%3G-1!H+0+!0+;+3,+4!P9!%&+! ;-3+6%!G64! G0+!$1+4! %.! 0+M$+1%!G6!
G;;+11!%.N+6Q!
!
Credential!
Value!
$1+06GF+!
j.+!
/G11H.04!
'O+4+0G%+!
!
U.%+Q! E&+! ;0+4+6%3G-1! /G11+4! ,3G! %&+! T+1.$0;+! "H6+0! 5G11H.04! ?0+4+6%3G-! I-.H! G0+! /0.;+11+4!
%&0.$7&!G!5367O+4+0G%+!5G11H.04! ?0+4+6%3G-! _G-34G%.0(! !E&+1+! ;0+4+6%3G-1! 4.!6.%!&G,+! %.!P+!
G! $1+06GF+! G64! /G11H.04:! %&+9! ;.$-4! P+! I.0! +KGF/ -+! G! $1+06GF+! ^! 58U! ;.FP36G%3.6! .0!
G6.%&+0!;0+4+6%3G-!%&G%!31!,G-34G%+4!P9!G!5?_(!
!
!
hEE5!T+M$+1%!
POST https://localhost:9031/as/token.oauth2 HTTP/1.1!
h+G4+01!
Content-Type:
Authorization:
application/x-www-form-urlencoded
Basic cm9fY2xpZW50OjJGZWRlcmF0ZQ==
d.49!
grant_type=password&username=joe&password=2Federate&scope=edit
!
8I!1$; ; +1 1I $ -:!%&+! ; -3+6 % !H3--! 0+ ; +3, + !G!' ) ) !"i!0+ 1/ .6 1+!%.!%& 31! 0+ M$ +1%!G64! %&+ ! G ;;+ 11!%.N+6! \G 64 ! . /%3. 6G -!
0+I0+1&!%.N+6]!H 3--!P+!0+%$ 06 +4 !36!G!b>" U !1%0$;%$ 0+Q!
!
!
OAuth!2.0!Developers!Guide!
!
<@!
!
hEE5!T+1/.61+!
HTTP/1.1 200 OK!
h+G4+01!
Content-Type:
application/json;charset=UTF-8
d.49!
{
"access_token":"zzz…yyy",
"token_type":"Bearer",
"expires_in":14400,
"refresh_token":"123…789"
}
!
U.%+Q! #6!+00.0!;.643%3.6!I0.F!%&+!G$%&+6%3;G%3.6!^!G$%&.03[G%3.6!/0.;+11!H3--!P+!0+%$06+4!%.!%&31!
;G--PG;N!XT8!H3%&!`+00.0a!G64!`+00.0g4+1;03/%3.6a!/G0GF+%+01(!
!
E&+! G//-3;G%3.6! ;G6! 6.H! /G01+! %&+! G;;+11! %.N+6! G64:! 3I! /0+1+6%:! %&+! 0+I0+1&! %.N+6! %.! $1+! I.0!
G$%&.03[G%3.6!%.!0+1.$0;+1(!!8I!G!0+I0+1&!%.N+6!HG1!0+%$06+4:!3%!;G6!P+!$1+4!%.!0+I0+1&!%&+!G;;+11!%.N+6!
.6;+!3%!+K/30+1(!
!
! !
!
OAuth!2.0!Developers!Guide!
!
<D!
!
2.5 Client!Credentials!
!
E&+! ;-3+6%! ;0+4+6%3G-1! %9/+! H . 0N 1! 36! G ! 13F3-G0! HG9! %. ! %&+! T"5?! 7 0G 6 %! %9/+! G64! 31! $1+4! %.! /0., 34 +! G6!
G;;+11!%.N+6!%.! G! ;-3+6%!PG1+4!.6! %&+!;0+4+6%3G-1!.0! %&+! ;-3+6%:!6.%!%&+!0+1.$0; +! .H6+ 0(! ! 86! %&31! 70G 6%!
%9/+:!%&+!;-3+6%!;0+4+ 6%3G-1!G0+ !1H G/ /+ 4!I.0!G 6!G; ;+11 !%.N+ 6!\1%+/ !<!P +-.H](!
!
!
!
!
Capability!
!
d0.H1+0ZPG1+4!+64!$1+0!36%+0G;%3.6!
U.!
?G6!$1+!+K%+06G-!8*5!I.0!G$%&+6%3;G%3.6 !
U.!
T+M$30+1!;-3+6%!G$%&+6%3;G%3.6!
e+1!
T+M$30+1!;-3+6%!%.!&G,+!N6.H-+47+!.I!$1+0!;0+4+6%3G-1!
U.!
T+I0+1&!%.N+6!G--.H+4!
U.!
#;;+11!%.N+6!31!36!;.6%+K%!.I!+64!$1+0!
U.!
!
2.5.1 Client!Configuration!
!
O.0!%&+!+KGF/-+1!P+-.H:!%&+!I.--.H367!;-3+6%!36I.0FG%3.6!H3--!P+!$1+4Q!
!
Protected API
Authorization Server
Resource Server
Client
User
1
!
OAuth!2.0!Developers!Guide!
!
')!
!
Admin!Label!
OAuth2!Parameter!
Example!Value!
?-3+6%!8*!
;-3+6%g34!
;;g;-3+6%!
?-3+6%!#$%&+6%3;G%3.6!
;-3+6%g/G11H.04!
'O+4+0G%+!
#--.H+4!20G6%!E9/+1!
70G6%g%9/+!
?-3+6%!?0+4+6%3G-1!
• 70G6%g%9/+!.I!`;-3+6%g;0+4 +6 %3G-1a !
>;./+!>+%%3671!\36!#>!
1+%%3671]!^!!
T+1%03;%!>;./+1!
1;./+!
+43%!
!
2.5.2 Request!access!token!
!
E&+!;-3+6%!FGN+1!G!0+M$+1%!\hEE5!5">E]!%.!%&+!%.N+6!+64/.36%!H3%&!%&+!;-3+6%!;0+4+6%3G-1!/0+1+6%+4!G1!
hEE5!dG13;!G$%&+6%3;G%3.6Q!
!
hEE5!T+M$+1%!
POST https://localhost:9031/as/token.oauth2 HTTP/1.1!
h+G4+01!
Content-Type:
Authorization:
application/x-www-form-urlencoded
Basic Y2NfY2xpZW50OjJGZWRlcmF0ZQ==
d.49!
grant_type=client_credentials&scope=edit
!
U.%+Q! E&+!;-3+6%!;0+4+6%3G-1! ;G6!G-1.! P +!/0.,34+4! $1367!%&+! ;-3+6%g34!G64!;-3+6%g1+;0+%!/G0GF+%+01!
36!%&+!;. 6 %+ 6% 1!. I!% & +!5 ">E(!
!
E&+!;-3+6%!H3--!0+;+3,+ !G!0+1/. 61+ !%.!%&31!0+M$ +1%(!!8I!1$;;+11I$ -:!G!'))!"i!0+1/ .6 1+!H 3--!P+!0+;+3,+ 4!G64 !
%&+!G;;+11!%.N+ 6!H 3--!P+!0+%$06 +4 !36!G!b>" U !1%0$;%$ 0+(!# !0+I0+1& !%.N+ 6!H 3--!U"E !P+ !0+%$06 +4 !%.!%&+ !;-3+6%(!
!
hEE5!T+1/.61+!
HTTP/1.1 200 OK!
h+G4+01!
Content-Type:
application/json;charset=UTF-8
d.49!
{
"access_token":"zzz…yyy",
"token_type":"Bearer",
"expires_in":14400,
}
!
!
OAuth!2.0!Developers!Guide!
!
'<!
!
2.6 Extension!grants!(i.e.!SAML!Bearer)!
!
E&+! +K%+613.6! 70G6%! %9/+! /0.,34+1! 1$//.0%! I.0! G443%3.6G-! 70G6%! %9/+1! +K%+64367! %&+! "#$%&'()!
1/+;3I3;G%3.61(!!#6!+KG F/ -+!31! %&+! $1+! .I! %&+! >#S c! '()! d+ G0+0!+K %+613.6! 70G6%(! ! 86!%&31! 70G6%! %9/+:! G! >#S c!
G11+0%3.6! \364 3;G%+ 4!P9!1%+/!<!P+-.H:!&.H+,+0!%&+!/0.;+11!$1+4!%.!G;M$30+!%&31!>#Sc!G11+0%3.6!31!.$%!.I!
1;./+!.I!%&31!4.;$F+6%]!;G6!P+!+K;&G67+4!I.0!G6!"#$%&!'()!G;;+11!%.N+6!\1%+/!'](!
!
!
!
!
!
Capability!
!
d0.H1+0ZPG1+4!+64!$1+0!36%+0G;%3.6!
U.f<!
?G6!$1+!+K%+06G-!8*5!I.0!G$%&+6%3;G%3.6 !
e+1f'!
T+M$30+1!;-3+6%!G$%&+6%3;G%3.6!
U.!
T+M$30+1!;-3+6%!%.!&G,+!N6.H-+47+!.I!$1+0!;0+4+6%3G-1!
U.!
T+I0+1&!%.N+6!G--.H+4!
U.!
#;;+11!%.N+6!31!36!;.6%+K%!.I!+64!$1+0!
SG9P+fA!
!
f<! k! #-%&.$7&! %&+! 70G6%! %9/+! 4.+16Y%! G--.H! I.0! $1+0! 36%+0G;%3.6:! %&+! /0.;+11! %.! 7+6+0G%+! %&+! >#Sc!
G11+0%3.6!$1+4!36 !%& 31!I-. H!;G6!36,. -, +!$ 1 +0 !36 %+ 0G; %3. 6 ( !
f'!k!#1!-.67!G1! %&+!5367O+4+0G%+!#>! 31!GP-+! %.! ,+03I9!%&+!>#S c! G11+0%3.6:!%&31!G11+0%3.6!;G6!P+!7+6+0G%+4!
I0.F!G!I.0+376 !>E >(!
fA!k!#;;+11!%.N+6!H3--!P+! 36! %&+! ;.6%+K%! .I! %&+! 1$Pj+;%!.I! %&+! >#S c! G11+0%3.6:!H&3;&!FG9!P+! G6!+64Z$1+0!
G!1+0,3;+!.0!%&+!;-3+6%!3%1+-I(!
2.6.1 Client!Configuration!
!
O.0!%&+!+KGF/-+1!P+-.H:!%&+!I.--.H367!;-3+6%!36I.0FG%3.6!H3--!P+!$1+4Q!
!
Protected API
Authorization Server
Resource Server
Client
User
1
2
!
OAuth!2.0!Developers!Guide!
!
''!
!
Admin!Label!
OAuth2!Parameter!
Example!Value!
?-3+6%!8*!
;-3+6%g34!
1GF-g;-3+6%!
?-3+6%!#$%&+6%3;G%3.6!
;-3+6%g/G11H.04!
'O+4+0G%+!
#--.H+4!20G6%!E9/+1!
70G6%g%9/+!
JK%+613.6!20G6%1!
• 70G6%g%9/+!.I! `$06Q3+%IQ/G0GF1Q.G$%&Q70G6%Z%9/+Q1GF-'Z
P+G0+0a!
>;./+!>+%%3671!\36!#>!
1+%%3671]!^!!
T+1%03;%!>;./+1!
1;./+!
+43%!
!
2.6.2 Request!access!token!
!
#%!%&31!1%G7+:!%&+!;-3+6%!&G1!G!>#S c!G11+0%3.6!%&G%!3%!6++41!%.!+K;&G67+!I.0!G6!"#$%&!'()!G;;+11!%.N+6(!!
E&+!/0.;+11!36! H&3;&! %&+! ;-3+6%!0+;+3,+4!%&+! G11+0%3.6!31!.$%! . I!1;./+! \3(+(!P..%1%0G/!G11+0%3.6:!>E>! %.N+6!
+K;&G67+]l!&.H+,+0:!%& +!;-3+6%!H.$ -4!dG1+CB!XTc!+6;.4+!%&+!G11+0%3.6! G64!36;-$4+! 3%!36!G!hEE5!5">E!%.!
%&+!%.N+6!+64 / .36%(!
!
O.0!%&+!+KGF/-+!P+-.H:!%&+!I.--.H367!>#Sc!G11+0%3.6!\GPP0+,3G%+4!I.0!0+G4GP3-3%9]!HG1!0+;+3,+4!P9!%&+!
;-3+6%!G64!31!$1+4!%.!0+M$+1%!G6!G;;+11!%.N+6Q!
!
PHNhbWw6QXNzZXJ0aW9uIElEPSJTdXdCSDdiQjM3cWVmT0tycmlaZkc3Y09H
ZUMiIElzc3VlSW5zdGFudD0iMjAxNC0wMy0xMFQxNjo1MjozOS43NTRaIiBW
...
UmVmPjwvc2FtbDpBdXRobkNvbnRleHQ-PC9zYW1sOkF1dGhuU3RhdGVtZW50
Pjwvc2FtbDpBc3NlcnRpb24-
!
hEE5!T+M$+1%!
POST https://localhost:9031/as/token.oauth2 HTTP/1.1!
h+G4+01!
Content-Type:
Authorization:
application/x-www-form-urlencoded
Basic c2FtbF9jbGllbnQ6MkZlZGVyYXRl
d.49!
grant_type=!urn:ietf:params:oauth:grant-type:saml2-bearer&assertion=!
PHNhbWw6QXNzZXJ0aW9uIElEPSJTdXdCSDdiQjM3cWVmT0tycmlaZkc3Y09HZUMiIElzc3VlSW5zd
GFudD0iMjAxNC0wMy0xMFQxNjo1MjozOS43NTRaIiBW...UmVmPjwvc2FtbDpBdXRobkNvbnRleHQ
-PC9zYW1sOkF1dGhuU3RhdGVtZW50Pjwvc2FtbDpBc3NlcnRpb24-&scope=edit
!
U.%+Q! E&+!;-3+6%!;0+4+6%3G-1! ;G6!G-1.!P+!/0.,34+4!$1367!%&+!;-3+6%g34!G64!;-3+6%g1+;0+%!/G0GF +%+01!
36!%&+!;. 6 %+ 6% 1!. I!% & +!5 ">E(!
!
E&+!;-3+6%!H3--!0+;+3,+!G!0+1/.61+!%.!%&31!0+M$+1%(!!8I!1$;;+11I$-:!G!'))!"i!0+1/.61+!H3--!P+!0+;+3,+4!G64!
%&+!G;;+11!%.N+ 6!H 3--!P+!0+%$06 +4 !36!G!b>" U !1%0$;%$ 0+(!#!0+I0+1&!%.N+6!H3--!U"E!P+!0+%$06+4!%.!%&+!;-3+6%(!
!
OAuth!2.0!Developers!Guide!
!
'A!
!
!
hEE5!T+1/.61+!
HTTP/1.1 200 OK!
h+G4+01!
Content-Type:
application/json;charset=UTF-8
d.49!
{
"access_token":"zzz…yyy",
"token_type":"Bearer",
"expires_in":14400,
}
!
!
OAuth!2.0!Developers!Guide!
!
'B!
!
3 Refresh'a'tok en!
!
8I! G ! 0+I0 + 1& ! %. N+ 6 ! HG1! 0+M$+1%+4!G-.67!H3%&!%&+!G;;+11!%.N+6:!%&+6!%&+!0+I0+1&!%.N+6!;G6!P+!$1+4!%.!
0+M$+1%!G! 6 +H ! G; ;+11 !%. N+ 6! H 3%&. $%! & G,36 7! %.! G1 N! %&+ !$ 1+0! %. !0+ZG$%&+6%3;G%+(!!8I!%&+!0+I0+1&!%.N+6!31!1%3--!
,G-34:!%&+6!G!6+H!G;;+11!%.N+6!G64!0+I0+1&!%.N+6!H3--!P+!0+%$06+4!%.!%&+!;-3+6%(!
!
8I! %& + ! 0+I0+ 1& ! %.N +6 ! &G1 ! P++ 6 ! 36,G -34 G% + 4 ! I.0! G69! 0+G 1. 6 :! %&+ 6 ! %&+! ;-3+6 %! F$ 1 %! 0+M $ 30+ ! %&+ ! $1+0 ! %.! 0+Z
G$%&+6%3;G%+!%.!0+%03+,+!G!6+H!G;;+11!%.N+6(!!E&+!0+G1.61!I.0!0+I0+1&!%.N+61!P+;.F367!36,G-34!G0+Q!
!
• T+I0+1&!%.N+6!&G1!+K/30+4l!
• T+I0+1&!%.N+6!&G1!P++6!G4F3631%0G%3,+-9!0+,.N+4!\1+/G0G%3.6!^!1+;$03%9!0+G1.61]l!
• X1+0!&G1!+K/-3;3%-9!0+,.N+4!%&+!0+I0+1&!%.N+6!
!
E.!0+I0+1&!G!%.N+6:!%&+!G;;+11!%.N+6!F$1%!&G,+!P++6!0+M$+1%+4! H3%&!G!70G6%!%9/+! %&G%!1$//.0%1!0+I0+1&!
%.N+61! \G$ %&. 03[G%3.6 ! ; .4 +! .0!0+1.$0;+! .H6 +0! /G11H .04! ;0+4+6 %3G-1](!!#!0+M$+1%! H3--!%&+6! P+! F G4 +! %.!
%&+!%.N+6!+64 / .36%!H 3%&!%& +!70G 6%g%9 /+ !/G0G F +%+ 0!1+%!%.!`0+ I0+1& g%. N+ 6a(!
!
U.%+Q! #! 6+H!G;;+11!%.N+6!;G6! P+!0+M$+1%+4!H 3%&! G!1;./+! .I!+M$G-! .0!-+11+0!,G-$+! %&G6!%&+! .03736G-!
G;;+11!%.N+6!0+M$+1%(!T+I0+ 1& 36 7!G6! G; ;+ 11!%.N+6!H3%&! G 4 4 3%3. 6 G-!1;./+1 ! H3--!0+%$0 6!G6! +00 .0(!
8I! %& +! 1;./ + ! /G0G F+%+0! 31! . F3%%+4:! %&+6! G;;+1 1! %.N+ 6 ! H3--! P+! ,G-34! I.0! %&+! .03736G -! 0+M$ +1 %!
1;./+(!
!
O.0!%&31!+KGF/-+:!%&+!G$%&.03[G%3.6!;.4+!;-3+6%!I0.F!GP.,+!H3--!P+!$1+4!%.!0+I0+1&! %& +!%. N+6 !
!
Admin!Label!
OAuth2!Parameter!
Example!Value!
?-3+6%!8*!
;-3+6%g34!
G;g;-3+6%!
?-3+6%!#$%&+6%3;G%3.6!
;-3+6%g/G11H.04!
'O+4+0G%+!
#--.H+4!20G6%!E9/+1!
0+1/.61+g%9/ +!
70G6%g%9/+!
#$%&.03[G%3.6!?.4+!
• 0+1/.61+g%9/ +!.I!`; .4 +a!
• 70G6%g%9/+!.I!`G$%&.03[G%3.6g;.4+a!
T+I0+1&!E.N+6!
T+430+;%!XT81!
0+430+;%g$03!
1GF/-+Q^^.G$%&'^;.4+^;P!
>;./+!>+%%3671!\36!#>!
1+%%3671]!^!!
T+1%03;%!>;./+1!
1;./+!
+43%!
T+I0+1&!E.N+6!
0+I0+1&g%.N+6!
<'A(((=@D!
!
!
E&+!I.--.H367!0+M$+1%!31!FG4+!P9!%&+!;-3+6%Q!
!
!
OAuth!2.0!Developers!Guide!
!
'W!
!
hEE5!T+M$+1%!
POST https://localhost:9031/as/token.oauth2 HTTP/1.1!
h+G4+01!
Content-Type:
Authorization:
application/x-www-form-urlencoded
Basic YWNfY2xpZW50OjJGZWRlcmF0ZQ==
d.49!
grant_type=refresh_token&refresh_token=123…789
!
U.%+Q! #! %.N+6! ;G6! .6-9! P+! 0+I0+1&+4! H3%&! %&+! 1GF+! .0! G! -+11+0! 1;./+! %&G6! %&+! .03736G-! %.N+6!
311$+4(! ! 8I! %&+! %.N+6! 31! P+367! 0+I0+1&+4! H3%&! %&+! 1GF+ ! 1;./+ ! G1! %&+! .03736G-! 0+M$+ 1 %:! %&+!
1;./+! /G0GF+%+0! ;G6! P+! .F3%%+4(! 8I! G! 70+G%+0! 1;./+! 31! 0+M$30+4:! %&+! ;-3+6%! F$1%! 0+Z
G$%&+6%3;G%+!%&+!$1+0(!
!
#! 1$;;+11I$-! 0+1 / . 61 + ! %.! %&31! F + 11 G7 + ! H3--! 0+1$-%! 36! G ! '))! "i! hEE5! 0+1/ . 6 1+ ! G64! %&+! I.--.H367! b> " U !
1%0$;%$0+!36!%&+!P.49!.I!%&+!0+1/.61+Q!
!
hEE5!T+1/.61+!
HTTP/1.1 200 OK!
h+G4+01!
Content-Type:
application/json;charset=UTF-8
d.49!
{
"access_token":"aaa…ccc",
"token_type":"Bearer",
"expires_in":14400,
"refresh_token":"456…321"
}
!
U.%+Q! *+/+64367! .6! %&+! 5367O+4+0G%+! ;.6I37$0G%3.6:! %&+! ;-3+6%! ;.$-4! P+! ;.6I37$0+4! %.! 0.--! %&+!
0+I0+1&!%.N+6!0+%$06+ 4! I0.F ! G!0+I0+1&! %.N+ 6! 0+M $+ 1%(!!3(+(!G!6+H!0+I0+1&!%.N+6!31!0+%$06+4 !
G64!%&+!.03736G-!0+I0+1&!%.N+ 6!31!36,G -34G%+ 4(!
!
!
OAuth!2.0!Developers!Guide!
!
'C!
!
4 Use$an"access!tok en!
!
#6!G;;+11!%.N+6!;G6!%&+6! P+!$1+4!G1!G6!G$%&.03[G%3.6! %.N+6!\6.%!%. !P+!;.6I$1+4!H3%&!%&+!G$%&. 03[G%3.6!
;.4+!36!%&+!G$%&. 03[ G% 3. 6 !;.4 +!70G 6% !%9/+ ]!%.!;.6I37$ 0+4 !H+P !1+0,3;+1(!!E.! $ 1+ !G6!G;;+11! %. N+ 6!%.!G;;+11!
G!/0.%+;%+4!0+1.$0;+:!%&+!G;;+11!%.N+6!F$1%!P+!/G11+4!%.!%&+!0+1.$0;+!1+0,+0(!
!
E&+!;-3+6%!1&.$-4!$1+! G! P+G0+0! G$%&.03[G%3.6! F+%&.4!G1! 4+I36+4!36!TO?! C=W)!%.! /0+1+6%! %&+! G;;+11! %.N+6!
%.!%&+!0+1.$ 0;+ (!!E&+!F.1%!;.FF.6!G//0.G;&!31!%.!$1+!%&+!hEE5!#$%&.03[G%3.6!&+G4+0!G64!36;-$4+!%&+!
G;;+11! %.N+6! G1! G! d+G0+0! G$%&.03[G%3.6! ;0+4+6%3G-l! &.H+,+0:! TO?! C=W)! G-1.! 4+I36+1! F+;&G631F1! I.0!
/0+1+6%367!G6!G;;+11!%.N+6!,3G!M$+09!1%0367!G64!36!G!/.1%!P.49(!
!
86!% & +!43G7 0G F!P +-. H:!%& + !;-3+6%!/0+1 +6 % 1!%&+!"# $ %& !'()! G ; ;+ 11!%.N+ 6!%.!%&+!/0.%+;%+ 4 !0+1.$ 0;+ !\1%+/!<](!!
E&+!0+1.$0;+!%&+6!,G-34G%+1!%&+!G;;+11!%.N+6!P+I.0+!0+%$06367!%&+!0+M$+1%+4!0+1.$0;+!\3I!G$%&.03[+4](!
!
!
!
O.0!+KGF/-+:!%.!+6G;%!G!2JE!0+M$+1%!.6!G!TJ>E!H+P!1+0,3;+:!73,+6!G6!G;;+11!%.N+6!`###(((mmma:!%&+!;-3+6%!
FGN+1!%&+!I.--.H367!hEE5!0+M$+1%Q!!
!
hEE5!T+M$+1%!
GET https://api.company.com/user HTTP/1.1!
h+G4+01!
Authorization:
Bearer AAA...ZZZ
d.49!
<N/A>
!
E&31!H3--!/0.,34+!%&+!G;;+11!%.N+6!%.!%&+!0+1.$0;+!1+0,+0:!H&3;&!;G6!%&+6!,G-34G%+!%&+!%.N+6 :!,+03I9!%&+!
1;./+! .0! %&+!0+M$+1%:!%&+! 34 + 6 %3%9 ! .I! %& + ! 0+1 .$ 0 ;+ ! .H 6 + 0! G6 4 ! %& + ! ;-3+6 % ! G6 4! / +0 I. 0F! %&+! G//0. / 03G %+ !
G;%3.6!3I!G$%&.03[+4(!
Protected API
Authorization Server
Resource Server
Client
User
1
2
!
OAuth!2.0!Developers!Guide!
!
'=!
!
API$Developer$Considerations!
!
!
OAuth!2.0!Developers!Guide!
!
'@!
!
5 Validate(a(token!
!
O.0!G6!#58!4+,+-./+0! %.!36%+70G%+! H3%&!"#$%&!'():!%&+!0+ 1.$ 0;+ !F$1%!G;;+/%!G64! ,G-34G%+!%&+! "#$%&!'()!
G;;+11! %.N+ 6! \1%+/! < ! P+-.H](! ! "6;+! %&+! %.N+6! &G1! P++6! 0+;+3,+4:! %&+! 0+ 1. $0;+ ! ;G6! %&+6! ,G-34G%+! %&+!
G;;+11! %.N+6! G7G361%! %&+! 5367O+4+0G%+! G$%&.03[G%3.6! 1+0,+0! \1%+/! '](! ! E&+! 0+1/.61+! I0.F! %&+! G;;+11!
%.N+6!,G-34G%3.6!H3--!36;-$4+!G%%03P$%+1!%&G%!%&+!0+1.$0;+!;G6!$1+!I.0!G$ %&. 03[G%3. 6!4 +;31 3.6 1(!
!
!
!
!
U.%+Q! E&31! 1+;%3.6! H3--! 4+F.61%0G%+! %&+! FG6$G-! F+%&.4! .I! ,G-34G%367! G6! G;;+11! %.N+6! %&0. $7& !
;.4+(!!E&31!+II.0%!;.$-4!G-1.!P+!&G64-+4!P9!G6!#58!7G%+HG9!^!1+0,3;+!P$1!G0;&3%+;%$0+(!
!
U.%+Q! E&+! "#$%&! '()! 1/+;3I3;G%3.61! 4.! 6 .%! 4+I36+! G! 1%G64G04! F+;&G631F! I.0! G;;+11! %.N+6!
,G-34G%3.6(! ! E&+! /0.;+11! 4+1;03P+4! 36! %&31! 1+;%3.6! 31! 1/+;3I3;! %.! G! 5367O+ 4+0G%+!
3F/-+F+6%G%3.6 ( !
!
5.1.1 Client!Configuration!
!
O.0!%&+!+KGF/-+1!P+-.H:!%&+!I.--.H367!;-3+6%!36I. 0F G%3. 6!H 3--!P+!$1+4 Q!
!
Admin!Label!
OAuth2!Parameter!
Example!Value!
?-3+6%!8*!
;-3+6%g34!
01g;-3+6%!
?-3+6%!#$%&+6%3;G%3.6!
;-3+6%g/G11H.04!
'O+4+0G%+!
#--.H+4!20G6%!E9/+1!
70G6%g%9/+!
#;;+11!E.N+6!_G-34G%3.6!\?-3+6%!31!G!T+1.$0;+!>+0,+0]!
• 70G6%g%9/+!.I!
`$06Q/36734+6%3%9(;.FQ.G$%&'Q70G6%g%9/+Q,G-34G%+gP+G
0+0a!
!
Protected API
Authorization Server
Resource Server
Client
User
1
2
!
OAuth!2.0!Developers!Guide!
!
'D!
!
E&+!#58!I301%!6++41!%.!0+;+3,+!%&+!G;;+11!%.N+6 !I0.F ! %&+ !;-3+6%l!%&31!/0.;+11!H 3--!36,.-,+! /G 01367!%& +! %.N+ 6!
,3G!G!/0.;+11!4+I36+4!36!TO?C=W)(!!>++!1+;%3.6!B!`X1+!G6!G;;+11!%.N+6a!GP.,+(!
!
#!0+M$+1%!I0.F!G!;-3+6%!H.$-4!-..N!13F3-G0!%.!%&+!I.--.H367Q!
!
hEE5!T+M$+1%!
GET https://api.company.com/user HTTP/1.1!
h+G4+01!
Authorization:
Bearer AAA...ZZZ
d.49!
<N/A>
!
86! . 0 4 + 0!%.!I$-I 3--!%&+ !0+M $ +1 %:!%&+ !#5 8!I301%!+K %0G ; %1 !%&+ !G;;+ 1 1!%.N + 6 !I0.F! %& + !G$ %& . 0 3[G %3. 6 !&+ G 4 + 0:!%&+ 6 !
M$+03+1!%&+!%.N+6!+64/.36%!.I!%&+!5367O+4+0G%+!#>!%.!,G-34G%+!%&+!%.N+6Q!
!
hEE5!T+M$+1%!
POST https://localhost:9031/as/token.oauth2 HTTP/1.1!
h+G4+01!
Content-Type:
Authorization:
application/x-www-form-urlencoded
Basic cnNfY2xpZW50OjJGZWRlcmF0ZQ==
d.49!
grant_type=urn:pingidentity.com:oauth2:grant_type:validate_bearer&token=AAA..
.ZZZ
!
#! 1$;;+11I$-!0+1/.61+!%.!%&31! F+11G7+!H3--!0+1$-%!36!G! '))!"i! hEE5!0+1/.61+!G64!G! b>"U!1%0$;%$0+!36!%&+!
P.49!.I!%&+!0+1/.61+!13F3-G0!%.!%&+!I.--.H367Q!
!
hEE5!T+1/.61+!
HTTP/1.1 200 OK!
h+G4+01!
Content-Type:
application/json;charset=UTF-8
d.49!
{
"access_token": { "role":”all_access” },
"token_type":"Bearer",
"expires_in":14400,
"scope":"edit",
"client_id":"ac_client"
}
!
!
OAuth!2.0!Developers!Guide!
!
A)!
!
E&+!0+1.$0;+!1+0,+0! ;G6!%&+6!$1+!%&31!36I.0FG%3.6!%.!FGN+!G6!G$%&.03[G%3.6!4 +;313.6!G64!G--.H!.0!4+69!
%&+!H+P!0+M $+ 1%(!
!
!
!
!
!
OAuth!2.0!Developers!Guide!
!
A<!
!
6 References!
!
"#$%&'!1/+;3I3;G%3.61!n!36I.0FG%3.6 !
&%%/Q^^.G$%&(6+%^'!
!
5367O+4+0G%+!#4F36!2$34+!
&%%/Q^^4.;$F+6%G%3.6(/36734+6%3%9(;.F^431/-G9^c5^50.4$;%o*.;$F+6%G%3.6!
!
5367!84+6%3%9!50.4$;%1!G64!*.H6-.G41!
&%%/1Q^^HHH(/36734+6%3%9(;.F^1$//.0%ZG64Z4.H6-.G41^!
!
!