AT&T VERIFY CONNECT (V3.0) INTEGRATION GUIDE FOR JAVASCRIPT LIBRARY

 
 
                                                                                          	
  
       AT&T	
  VERIFY	
  CONNECT	
  (V3.0)	
  INTEGRATION	
  
            GUIDE	
  FOR	
  JAVASCRIPT	
  LIBRARY	
  
                                                                AT&T-­‐UN034	
  
	
  
AT&T	
  Verify	
  Connect	
  is	
  powered	
  by	
  SecureKey	
  Technologies	
  Inc.	
  briidge.net	
  Connect	
  service	
  platform.	
  
©2014	
  SecureKey	
  Technologies	
  Inc.	
  and	
  AT&T	
  Intellectual	
  Property.	
  	
  All	
  Rights	
  Reserved.	
  	
  No	
  part	
  of	
  this	
  
document	
   may	
   be	
   copied,	
   modified	
   or	
   disseminated	
   without	
   permission	
   of	
   SecureKey	
   and	
   AT&T.	
   AT&T	
  
and	
   the	
   AT&T	
   logo	
   are	
   trademarks	
   of	
   AT&T	
   Intellectual	
   Property.	
   SecureKey	
   and	
   briidge.net	
   are	
  
trademarks	
  of	
  SecureKey	
  Technologies.	
  Other	
  marks	
  are	
  property	
  of	
  their	
  respective	
  owners.

               Revision:	
  1.1	
  
               Effective	
  Date:	
  14	
  Aug	
  2014	
  
               Owner:	
  AT&T	
  

               ©	
  2014	
  AT&T	
  intellectual	
  property.	
  all	
  rights	
  reserved.	
  AT&T,	
  the	
  AT&T	
  logo	
  and	
  all	
  other	
  AT&T	
  marks	
  contained	
  
               herein	
  are	
  trademarks	
  of	
  AT&T	
  intellectual	
  property	
  and/or	
  AT&T	
  affiliated	
  companies	
  
AT&T 	
   V ERIFY	
   C ONNECT	
   ( V 3.0) 	
   I NTEGRATION	
   G UIDE	
   F OR	
   J AVA S CRIPT	
   L IBRARY	
                              	
  

Table	
  of	
  Contents	
  
1.	
   Introduction ............................................................................................................................... 4	
  
    1.1	
   About	
  AT&T®	
  Verify	
  Connect ................................................................................................. 4	
  
    1.2	
   Audience .............................................................................................................................. 4	
  
    1.3	
   Notation .............................................................................................................................. 4	
  
    1.4	
   What’s	
  New	
  in	
  this	
  Version .................................................................................................... 4	
  
    1.5	
   Supported	
  Operating	
  Systems	
  and	
  Browsers ........................................................................... 5	
  
        1.5.1	
   Operating	
  Systems .......................................................................................................... 5	
  
        1.5.2	
   Supported	
  Browsers ....................................................................................................... 5	
  
        1.5.3	
   AT&T-­‐Certified	
  Card	
  Readers	
  /	
  Devices ............................................................................. 5	
  
2.	
   AT&T®	
  Verify	
  Connect ................................................................................................................. 6	
  
    2.1	
   Solution	
  Overview ................................................................................................................. 6	
  
        2.1.1	
   Supported	
  Devices .......................................................................................................... 7	
  
        2.1.2	
   Localization	
  Support ....................................................................................................... 7	
  
    2.2	
   Using	
  the	
  JavaScript	
  Library ................................................................................................... 8	
  
3.	
   AT&T	
  Verify	
  Connect	
  API	
  Guide ................................................................................................... 9	
  
    3.1	
   AT&T	
  Verify	
  Connect	
  URLs ..................................................................................................... 9	
  
    3.2	
   User	
  Interaction	
  Requests .................................................................................................... 10	
  
        3.2.1	
   User	
  Authentication ...................................................................................................... 11	
  
        3.2.2	
   User	
  Confirmation ........................................................................................................ 15	
  
        3.2.3	
   Read	
  Card .................................................................................................................... 18	
  
        3.2.4	
   Get	
  Connected	
  Device	
  ID ............................................................................................... 21	
  
        3.2.5	
   Cancel	
  Request ............................................................................................................. 23	
  
    3.3	
   User	
  Registration	
  /	
  Management ......................................................................................... 24	
  
        3.3.1	
   Add	
  User ...................................................................................................................... 25	
  
        3.3.2	
   Get	
  User ...................................................................................................................... 26	
  
        3.3.3	
   Remove	
  User ................................................................................................................ 27	
  
        3.3.4	
   Update	
  User ................................................................................................................. 27	
  
        3.3.5	
   VerifyDevice ................................................................................................................. 29	
  
        3.3.6	
   DeVerifyDevices ........................................................................................................... 30	
  
        3.3.7	
   Pair	
  Device ................................................................................................................... 31	
  
    3.4	
   Device	
  Management ........................................................................................................... 34	
  

©	
  2014	
  AT&T	
  intellectual	
  property.	
  all	
  rights	
  reserved.	
  AT&T,	
  the	
  AT&T	
  logo	
             Effective	
  Date:	
  14	
  August	
  2014	
  
and	
  all	
  other	
  AT&T	
  marks	
  contained	
  herein	
  are	
  trademarks	
  of	
  AT&T	
  
                                                                                                                                                        Page	
  2	
  of	
  63
intellectual	
  property	
  and/or	
  AT&T	
  affiliated	
  companies	
  
AT&T 	
   V ERIFY	
   C ONNECT	
   ( V 3.0) 	
   I NTEGRATION	
   G UIDE	
   F OR	
   J AVA S CRIPT	
   L IBRARY	
                              	
  

          3.4.1	
   Get	
  Devices .................................................................................................................. 34	
  
          3.4.2	
   Get	
  Device	
  by	
  ID ........................................................................................................... 35	
  
          3.4.3	
   Add	
  Device ................................................................................................................... 36	
  
          3.4.4	
   Remove	
  Device ............................................................................................................. 37	
  
          3.4.5	
   Remove	
  All	
  User	
  Devices ............................................................................................... 37	
  
          3.4.6	
   Get	
  Device	
  Provision	
  Id ................................................................................................. 38	
  
       3.5	
   Attribute	
  Management ........................................................................................................ 39	
  
          3.5.1	
   Set	
  Attributes ............................................................................................................... 39	
  
          3.5.2	
   Get	
  All	
  Attributes .......................................................................................................... 40	
  
          3.5.3	
   Get	
  Attributes .............................................................................................................. 41	
  
4.	
   AT&T	
  Verify	
  Connect	
  JavaScript	
  Library ...................................................................................... 43	
  
       4.1	
   Including	
  the	
  AT&T	
  Verify	
  Connect	
  JavaScript	
  Library ............................................................. 43	
  
       4.2	
   Setting	
  override	
  parameters ................................................................................................ 43	
  
       4.3	
   Initializing	
  the	
  AT&T	
  Verify	
  Connect	
  Widget .......................................................................... 44	
  
          4.3.1	
   SKAP.init	
  parameters .................................................................................................... 44	
  
          4.3.2	
   SKAP.init	
  exceptions ..................................................................................................... 45	
  
          4.3.3	
   Sample	
  design .............................................................................................................. 46	
  
       4.4	
   Pair	
  Device ......................................................................................................................... 47	
  
          4.4.1	
   SKAP.pairDevice	
  parameters.......................................................................................... 47	
  
          4.4.2	
   SKAP.pairDevice	
  exceptions ........................................................................................... 48	
  
          4.4.3	
   Callback	
  functions ......................................................................................................... 48	
  
       4.5	
   Update	
  Plugin ..................................................................................................................... 48	
  
          4.5.1	
   SKAP.updatePlugin	
  parameters ...................................................................................... 49	
  
          4.5.2	
   SKAP.updatePlugin	
  exceptions ....................................................................................... 50	
  
          4.5.3	
   Callback	
  functions ......................................................................................................... 50	
  
Appendix A	
   Request	
  Properties .................................................................................................. 51	
  
Appendix B	
   Response	
  Properties ................................................................................................ 56	
  
Appendix C	
   Error	
  Codes ............................................................................................................. 61	
  
	
                                                             	
  

©	
  2014	
  AT&T	
  intellectual	
  property.	
  all	
  rights	
  reserved.	
  AT&T,	
  the	
  AT&T	
  logo	
             Effective	
  Date:	
  14	
  August	
  2014	
  
and	
  all	
  other	
  AT&T	
  marks	
  contained	
  herein	
  are	
  trademarks	
  of	
  AT&T	
  
                                                                                                                                                        Page	
  3	
  of	
  63
intellectual	
  property	
  and/or	
  AT&T	
  affiliated	
  companies	
  
AT&T 	
   V ERIFY	
   C ONNECT	
   ( V 3.0) 	
   I NTEGRATION	
   G UIDE	
   F OR	
   J AVA S CRIPT	
   L IBRARY	
                              	
  

1. Introduction	
  

1.1         About	
  AT&T®	
  Verify	
  Connect	
  
AT&T	
  Verify	
  Connect	
  is	
  a	
  cloud-­‐based	
  multi-­‐factor	
  authentication	
  service	
  platform	
  that	
  provides	
  
customers	
  the	
  ability	
  to	
  strongly	
  authenticate	
  their	
  users.	
  The	
  platform	
  is	
  designed	
  to	
  support	
  all	
  in-­‐
market	
  devices	
  today,	
  enabling	
  strong	
  security	
  across	
  all	
  delivery	
  channels.	
  

1.2         Audience	
  
This	
  guide	
  assumes	
  that	
  the	
  reader	
  is	
  generally	
  familiar	
  with	
  the	
  OAuth	
  2.0	
  authorization	
  framework,	
  
JSON	
  requests,	
  and	
  using	
  X.509	
  certificates	
  for	
  secure	
  communication	
  over	
  HTTPS	
  (TLS	
  1.0+).	
  

1.3         Notation	
  
A	
  Relying	
  Party	
  (RP)	
  is	
  a	
  person	
  or	
  organization	
  that	
  is	
  interested	
  in	
  verifying	
  and	
  establishing	
  the	
  
credential	
  of	
  another	
  person	
  with	
  AT&T	
  Verify	
  Connect	
  platform.	
  

1.4         What’s	
  New	
  in	
  this	
  Version	
  
       •       AT&T	
  Verify	
  Connect	
  Server	
  has	
  removed	
  session	
  requirement	
  for	
  server	
  calls.	
  However,	
  existing	
  
               services	
  that	
  use	
  sessions	
  can	
  continue	
  to	
  use	
  sessions	
  in	
  their	
  flows.	
  
       •       Support	
  now	
  available	
  for	
  card	
  readers	
  based	
  on	
  PC/SC	
  (Personal	
  Computer/Smart	
  card)	
  
               standard	
  framework.	
  This	
  enables	
  the	
  use	
  of	
  widely	
  available	
  in-­‐market	
  card	
  readers	
  with	
  all	
  
               AT&T	
  Verify	
  Connect	
  offerings.	
  
       •       AT&T	
  Verify	
  Connect	
  Server	
  API	
  has	
  changed	
  the	
  object	
  structure	
  for	
  DeviceConstraints.	
  The	
  
               Boolean	
  values	
  embeddedLocalAllowed	
  and	
  removableLocalAllowed	
  have	
  been	
  replaced	
  by	
  a	
  List	
  
               type	
  called	
  allowedSETypes.	
  The	
  default	
  value	
  is	
  null,	
  which	
  means	
  all	
  the	
  supported	
  SE	
  types	
  are	
  
               allowed.	
  See	
  DeviceConstraints	
  description	
  here.	
  
       •       Attribute	
  locker	
  enables	
  customers	
  to	
  securely	
  store	
  and	
  retrieve	
  end	
  user	
  information	
  from	
  the	
  
               AT&T	
  Verify	
  Connect	
  servers.	
  This	
  feature	
  is	
  currently	
  available	
  with	
  server-­‐to-­‐server	
  calls	
  only.	
  
               See	
  the	
  following	
  methods	
  from	
  your	
  integration	
  guide:	
  
                       o       set-­‐attributes.action	
  method	
  enables	
  you	
  to	
  store	
  custom	
  attributes	
  on	
  AT&T	
  Verify	
  
                               Connect	
  server	
  using	
  name/value	
  pairs.	
  
                       o       get-­‐all-­‐attributes.action	
  method	
  enables	
  you	
  to	
  retrieve	
  all	
  stored	
  attributes	
  for	
  a	
  given	
  
                               user.	
  
                       o       get-­‐attributes.action	
  method	
  enables	
  you	
  to	
  retrieve	
  specific	
  attributes	
  for	
  a	
  given	
  user.	
  
               See	
  Section	
  3.5:	
  Attribute	
  Management	
  for	
  details.	
  
       •       All	
  user	
  interfaces	
  provided	
  with	
  AT&T	
  Verify	
  Connect	
  offerings	
  are	
  now	
  compliant	
  with	
  WCAG	
  
               2.0	
  web	
  accessibility	
  standards.	
                                                   	
  

©	
  2014	
  AT&T	
  intellectual	
  property.	
  all	
  rights	
  reserved.	
  AT&T,	
  the	
  AT&T	
  logo	
             Effective	
  Date:	
  14	
  August	
  2014	
  
and	
  all	
  other	
  AT&T	
  marks	
  contained	
  herein	
  are	
  trademarks	
  of	
  AT&T	
  
                                                                                                                                                        Page	
  4	
  of	
  63
intellectual	
  property	
  and/or	
  AT&T	
  affiliated	
  companies	
  
AT&T 	
   V ERIFY	
   C ONNECT	
   ( V 3.0) 	
   I NTEGRATION	
   G UIDE	
   F OR	
   J AVA S CRIPT	
   L IBRARY	
                              	
  

1.5         Supported	
  Operating	
  Systems	
  and	
  Browsers	
  
AT&T	
  Verify	
  Connect	
  applications	
  are	
  supported	
  on	
  the	
  following	
  device	
  operating	
  systems,	
  desktop	
  
operating	
  systems,	
  and	
  browsers.	
  

1.5.1          Operating	
  Systems	
  
       •       Windows	
  XP	
  
       •       Windows	
  Vista	
  
       •       Windows	
  7	
  
       •       Windows	
  8	
  
       •       Windows	
  8.1	
  
       •       OSX	
  10.6	
  “Snow	
  Leopard”	
  
       •       OSX	
  10.7	
  “Lion”	
  
       •       OSX	
  10.8	
  “Mountain	
  Lion”	
  
       •       OSX	
  10.9	
  “Mavericks”	
  

1.5.2          Supported	
  Browsers	
  
       •       Internet	
  Explorer	
  v7+	
  
       •       Firefox	
  v27-­‐v25	
  
       •       Chrome	
  v33-­‐v32	
  
       •       Safari	
  v5.1.10,	
  v6.1.1,	
  and	
  v7.0.1	
  

1.5.3          AT&T-­‐Certified	
  Card	
  Readers	
  /	
  Devices	
  
       •       Advanced	
  Card	
  Systems	
  (ACS)	
  Card	
  Reader	
  (PC/SC-­‐compliant):	
  
                       o       ACR122T	
  USB	
  Token	
  NFC	
  Reader	
  
                       o       ACR122U	
  USB	
  NFC	
  Reader	
  
       •       SecureKey	
  Card	
  Reader	
  
       •       IPT	
  Card	
  Reader	
  
	
  
       Note:	
  This	
  list	
  is	
  only	
  applicable	
  for	
  Windows	
  platform	
  applications.	
  
	
                                                             	
  

©	
  2014	
  AT&T	
  intellectual	
  property.	
  all	
  rights	
  reserved.	
  AT&T,	
  the	
  AT&T	
  logo	
             Effective	
  Date:	
  14	
  August	
  2014	
  
and	
  all	
  other	
  AT&T	
  marks	
  contained	
  herein	
  are	
  trademarks	
  of	
  AT&T	
  
                                                                                                                                                        Page	
  5	
  of	
  63
intellectual	
  property	
  and/or	
  AT&T	
  affiliated	
  companies	
  
AT&T 	
   V ERIFY	
   C ONNECT	
   ( V 3.0) 	
   I NTEGRATION	
   G UIDE	
   F OR	
   J AVA S CRIPT	
   L IBRARY	
                              	
  

2. AT&T®	
  Verify	
  Connect	
  
The	
  following	
  chapter	
  is	
  a	
  summary	
  overview	
  of	
  the	
  AT&T	
  Verify	
  Connect	
  solution	
  for	
  multi-­‐factor	
  
authentication.	
  This	
  chapter	
  discusses	
  usage	
  scenarios	
  and	
  their	
  requirements	
  for	
  quickly	
  setting	
  up	
  
complete	
  authentication	
  solutions	
  for	
  your	
  application	
  or	
  enhancing	
  existing	
  applications	
  for	
  multi-­‐factor	
  
authentication.	
  

2.1         Solution	
  Overview	
  
AT&T	
  Verify	
  Connect	
  is	
  an	
  API-­‐based	
  solution	
  with	
  both	
  client	
  and	
  server	
  level	
  integration	
  in	
  a	
  Relying	
  
Party	
  (RP)	
  application.	
  The	
  Connect	
  client	
  component	
  communicates	
  with	
  the	
  RP	
  application	
  client	
  to	
  
initiate	
  all	
  authentication	
  requests	
  with	
  the	
  AT&T	
  Verify	
  Connect	
  server.	
  The	
  Connect	
  server	
  component	
  
communicates	
  directly	
  with	
  the	
  AT&T	
  Verify	
  Connect	
  server	
  to	
  retrieve	
  authentication	
  data.	
  
The	
  following	
  diagram	
  shows	
  the	
  logical	
  communication	
  lines	
  between	
  AT&T	
  Verify	
  Connect	
  components	
  
and	
  an	
  RP	
  application.	
  

A	
  Relying	
  Party	
  (RP)	
  must	
  implement	
  client	
  and	
  server	
  handlers	
  to	
  fully	
  integrate	
  their	
  application	
  with	
  
AT&T	
  Verify	
  Connect.	
  
	
                                                             	
  

©	
  2014	
  AT&T	
  intellectual	
  property.	
  all	
  rights	
  reserved.	
  AT&T,	
  the	
  AT&T	
  logo	
             Effective	
  Date:	
  14	
  August	
  2014	
  
and	
  all	
  other	
  AT&T	
  marks	
  contained	
  herein	
  are	
  trademarks	
  of	
  AT&T	
  
                                                                                                                                                        Page	
  6	
  of	
  63
intellectual	
  property	
  and/or	
  AT&T	
  affiliated	
  companies	
  
AT&T 	
   V ERIFY	
   C ONNECT	
   ( V 3.0) 	
   I NTEGRATION	
   G UIDE	
   F OR	
   J AVA S CRIPT	
   L IBRARY	
                              	
  

2.1.1          Supported	
  Devices	
  
AT&T	
  Verify	
  Connect	
  can	
  enable	
  second	
  factor	
  authentication	
  using	
  a	
  variety	
  of	
  devices	
  such	
  as:	
  
       •       Smart	
  phones	
  
       •       Tablets	
  
       •       Personal	
  Computers	
  
       •       USB	
  Card	
  Readers	
  for	
  NFC	
  supported	
  cards	
  with	
  Pin-­‐and-­‐Chip	
  technology	
  
Each	
  supported	
  device	
  includes	
  a	
  secure	
  applet	
  that	
  is	
  personalized	
  with	
  a	
  unique	
  identifier	
  and	
  
cryptographic	
  keys.	
  A	
  separate	
  application	
  on	
  the	
  device	
  provides	
  the	
  user	
  interface	
  for	
  facilitating	
  the	
  
authentication	
  flows	
  on	
  the	
  device.	
  This	
  application	
  also	
  facilitates	
  communication	
  with	
  the	
  AT&T	
  Verify	
  
Connect	
  server	
  and	
  with	
  the	
  secure	
  applet.	
  
Most	
  supported	
  devices	
  support	
  NFC	
  communication	
  and	
  provide	
  the	
  ability	
  to	
  read	
  ISO	
  14443	
  smart	
  
cards.	
  These	
  devices	
  can	
  be	
  used	
  to:	
  
       •       Provide	
  clients	
  with	
  remote	
  card	
  reading	
  terminals	
  for	
  reading	
  contactless	
  cards	
  that	
  users	
  hold.	
  
       •       Verify	
  user	
  identity	
  based	
  on	
  the	
  presentation	
  of	
  a	
  contactless	
  credential.	
  In	
  this	
  scenario	
  AT&T	
  
               Verify	
  Connect	
  requires	
  access	
  to	
  a	
  mapping	
  between	
  the	
  user	
  identifier	
  and	
  the	
  on	
  card	
  data	
  
               (e.g.	
  PAN).	
  

2.1.2          Localization	
  Support	
  
RPs	
  integrate	
  with	
  AT&T	
  Verify	
  Connect	
  using	
  a	
  JSON-­‐based	
  API	
  and	
  a	
  JavaScript	
  library	
  that	
  is	
  included	
  in	
  
the	
  RP	
  application	
  client.	
  This	
  integration	
  is	
  described	
  in	
  subsequent	
  sections.	
  During	
  runtime,	
  RPs	
  must	
  
specify	
  a	
  language	
  code	
  within	
  requests.	
  The	
  following	
  ISO	
  language	
  and	
  country	
  code	
  combinations	
  are	
  
supported:	
  
       •       en-­‐CA	
  –	
  English	
  (Canada)	
  
       •       en-­‐US	
  –	
  English	
  (US)	
  
       •       en-­‐AU	
  –	
  English	
  (Australia)	
  
       •       en-­‐GB	
  –	
  English	
  (United	
  Kingdom)	
  
       •       es-­‐ES	
  –	
  Spanish	
  (Spain)	
  
       •       fr-­‐CA	
  –	
  French	
  (Canada)	
  
       •       it-­‐IT	
  –	
  Italian	
  (Italy)	
  
       •       he-­‐IL	
  –	
  Hebrew	
  (Israel)	
  
       •       pt-­‐BR	
  –	
  Portuguese	
  (Brazil)	
  
       •       sv-­‐SE	
  –	
  Swedish	
  (Sweden)	
  

	
                                                             	
  

©	
  2014	
  AT&T	
  intellectual	
  property.	
  all	
  rights	
  reserved.	
  AT&T,	
  the	
  AT&T	
  logo	
             Effective	
  Date:	
  14	
  August	
  2014	
  
and	
  all	
  other	
  AT&T	
  marks	
  contained	
  herein	
  are	
  trademarks	
  of	
  AT&T	
  
                                                                                                                                                        Page	
  7	
  of	
  63
intellectual	
  property	
  and/or	
  AT&T	
  affiliated	
  companies	
  
AT&T 	
   V ERIFY	
   C ONNECT	
   ( V 3.0) 	
   I NTEGRATION	
   G UIDE	
   F OR	
   J AVA S CRIPT	
   L IBRARY	
                              	
  

2.2         Using	
  the	
  JavaScript	
  Library	
  
The	
  following	
  describes	
  the	
  steps	
  involved	
  for	
  an	
  RP	
  application	
  to	
  successfully	
  authenticate	
  users	
  using	
  
the	
  JavaScript	
  library.	
  
       1.      RP	
  Server	
  initiates	
  a	
  request	
  for	
  AT&T	
  Verify	
  Connect	
  functionality.	
  
               AT&T	
  Verify	
  Connect	
  returns	
  a	
  response	
  containing	
  a	
  transaction	
  identifier	
  and	
  a	
  widget	
  code,	
  
               where	
  the:	
  
                       •       Transaction	
  identifier	
  is	
  used	
  in	
  subsequent	
  server	
  to	
  server	
  calls	
  to	
  AT&T	
  Verify	
  
                               Connect	
  to	
  reference	
  this	
  user;	
  
                       •       Widget	
  code	
  is	
  used	
  to	
  initiate	
  the	
  AT&T	
  Verify	
  Connect	
  widget	
  from	
  the	
  client	
  
                               application.	
  The	
  widget	
  provides	
  the	
  necessary	
  UI	
  components	
  for	
  users	
  to	
  select	
  from	
  a	
  
                               list	
  of	
  supported	
  devices.	
  
       2.      RP	
  Server	
  passes	
  the	
  widget	
  code	
  to	
  the	
  RP	
  client	
  to	
  initiate	
  the	
  AT&T	
  Verify	
  Connect	
  widget.	
  
       3.      RP	
  Client	
  loads	
  the	
  JavaScript	
  library	
  and	
  calls	
  the	
  widget	
  using	
  the	
  widget	
  code	
  passed	
  from	
  the	
  
               RP	
  server.	
  The	
  widget	
  guides	
  the	
  end	
  user	
  through	
  the	
  authentication	
  process.	
  
       4.      RP	
  Client	
  waits	
  while	
  the	
  user	
  interacts	
  with	
  the	
  widget	
  to	
  retrieve	
  the	
  device	
  information.	
  
               During	
  authentication	
  the	
  widget	
  can	
  trigger	
  the	
  following	
  events:	
  
                       •       Successful	
  connection	
  
                               This	
  event	
  indicates	
  the	
  widget	
  has	
  successfully	
  connected	
  with	
  AT&T	
  Verify	
  Connect.	
  
                       •       Authentication	
  complete	
  
                               This	
  event	
  indicates	
  the	
  widget	
  flow	
  has	
  completed.	
  
               The	
  RP	
  Client	
  is	
  expected	
  to	
  implement	
  appropriate	
  handlers	
  to	
  listen	
  for	
  these	
  events.	
  
       5.      RP	
  Client	
  handles	
  these	
  events	
  and	
  notifies	
  the	
  RP	
  server	
  when	
  the	
  authentication	
  completes.	
  
       6.      RP	
  Server	
  calls	
  AT&T	
  Verify	
  Connect,	
  referencing	
  the	
  transaction	
  identifier	
  and	
  the	
  access	
  token,	
  
               to	
  retrieve	
  the	
  device	
  information	
  for	
  this	
  user.	
  
After	
  the	
  RP	
  server	
  requests	
  the	
  device	
  information,	
  AT&T	
  Verify	
  Connect	
  returns	
  the	
  appropriate	
  device	
  
information,	
  if	
  successful.	
  During	
  this	
  time,	
  the	
  RP	
  can	
  decide	
  to	
  give	
  the	
  user	
  access	
  to	
  the	
  RP	
  resource.	
  
	
                                                             	
  

©	
  2014	
  AT&T	
  intellectual	
  property.	
  all	
  rights	
  reserved.	
  AT&T,	
  the	
  AT&T	
  logo	
             Effective	
  Date:	
  14	
  August	
  2014	
  
and	
  all	
  other	
  AT&T	
  marks	
  contained	
  herein	
  are	
  trademarks	
  of	
  AT&T	
  
                                                                                                                                                        Page	
  8	
  of	
  63
intellectual	
  property	
  and/or	
  AT&T	
  affiliated	
  companies	
  
AT&T 	
   V ERIFY	
   C ONNECT	
   ( V 3.0) 	
   I NTEGRATION	
   G UIDE	
   F OR	
   J AVA S CRIPT	
   L IBRARY	
                              	
  

3. AT&T	
  Verify	
  Connect	
  API	
  Guide	
  
The	
  AT&T	
  Verify	
  Connect	
  JSON	
  API	
  is	
  a	
  server-­‐to-­‐server	
  API	
  that	
  facilitates	
  initiation	
  of	
  functional	
  AT&T	
  
Verify	
  Connect	
  methods.	
  The	
  following	
  points	
  are	
  common	
  to	
  all	
  calls	
  described	
  in	
  this	
  section:	
  
       •       Transport	
  Protocol	
  
               HTTPS	
  (TLS	
  1.0+)	
  is	
  required	
  for	
  communication	
  between	
  the	
  RP’s	
  web	
  site	
  and	
  the	
  AT&T	
  Verify	
  
               Connect	
  server.	
  Authentication	
  is	
  performed	
  via	
  a	
  client	
  X.509	
  certificate.	
  Requests	
  will	
  use	
  the	
  
               POST	
  method.	
  
       •       JSON	
  Requests	
  
               Many	
  of	
  the	
  requests	
  exposed	
  through	
  the	
  API	
  provide	
  parameters.	
  These	
  parameters	
  are	
  
               passed	
  in	
  JSON	
  format	
  in	
  the	
  body	
  of	
  the	
  HTTP	
  POST	
  message.	
  
       •       HTTP	
  Responses	
  
               The	
  HTTP	
  response	
  code	
  will	
  report	
  the	
  status	
  of	
  the	
  HTTP	
  communication	
  and	
  not	
  the	
  status	
  of	
  
               the	
  AT&T	
  Verify	
  Connect	
  transaction.	
  This	
  means	
  that	
  all	
  messages	
  that	
  are	
  accepted	
  and	
  
               processed	
  by	
  the	
  server	
  will	
  return	
  an	
  HTTP	
  200	
  status	
  code.	
  Responses	
  provided	
  with	
  a	
  200	
  
               response	
  code	
  must	
  be	
  checked	
  for	
  an	
  error	
  element	
  to	
  determine	
  if	
  the	
  request	
  was	
  successful.	
  	
  

3.1         AT&T	
  Verify	
  Connect	
  URLs	
  
In	
  the	
  following	
  sections,	
  URLs	
  will	
  be	
  shown	
  with	
  the	
  host	
  portion	
  as	
  [Host].	
  [Host]	
  is	
  a	
  placeholder	
  for	
  
the	
  AT&T	
  Verify	
  Connect	
  server	
  hostname	
  that	
  will	
  be	
  used.	
  There	
  are	
  various	
  AT&T	
  Verify	
  Connect	
  
environments,	
  from	
  Sandbox	
  development	
  environments	
  to	
  Production.	
  The	
  appropriate	
  host	
  value	
  to	
  
use	
  for	
  a	
  particular	
  purpose	
  is	
  provided	
  by	
  SecureKey.	
  

	
                                                             	
  

©	
  2014	
  AT&T	
  intellectual	
  property.	
  all	
  rights	
  reserved.	
  AT&T,	
  the	
  AT&T	
  logo	
             Effective	
  Date:	
  14	
  August	
  2014	
  
and	
  all	
  other	
  AT&T	
  marks	
  contained	
  herein	
  are	
  trademarks	
  of	
  AT&T	
  
                                                                                                                                                        Page	
  9	
  of	
  63
intellectual	
  property	
  and/or	
  AT&T	
  affiliated	
  companies	
  
AT&T 	
   V ERIFY	
   C ONNECT	
   ( V 3.0) 	
   I NTEGRATION	
   G UIDE	
   F OR	
   J AVA S CRIPT	
   L IBRARY	
                              	
  

3.2         User	
  Interaction	
  Requests	
  
All	
  requests	
  that	
  involve	
  the	
  end	
  user	
  follow	
  an	
  asynchronous	
  completion	
  model.	
  User	
  interactions	
  can	
  
include	
  activities	
  such	
  as	
  card	
  reading,	
  device	
  recognition,	
  and	
  entering	
  or	
  setting	
  up	
  passcodes.	
  	
  
The	
  RP	
  application	
  server	
  initiates	
  an	
  API	
  request	
  with	
  AT&T	
  Verify	
  Connect	
  and	
  passes	
  a	
  unique	
  
transaction	
  identifier	
  and	
  widget	
  code	
  to	
  its	
  application	
  client.	
  The	
  application	
  client	
  loads	
  the	
  AT&T	
  
Verify	
  Connect	
  JavaScript	
  library	
  with	
  the	
  provided	
  widget	
  code;	
  launching	
  the	
  user	
  interfaces	
  to	
  fulfill	
  the	
  
request.	
  After	
  the	
  user	
  completes	
  the	
  transaction	
  a	
  notification	
  is	
  sent	
  to	
  the	
  application	
  client,	
  which	
  in	
  
turn	
  is	
  passed	
  to	
  the	
  application	
  server	
  to	
  complete	
  the	
  request.	
  The	
  application	
  server	
  makes	
  an	
  
additional	
  API	
  request	
  with	
  AT&T	
  Verify	
  Connect	
  to	
  retrieve	
  the	
  resulting	
  information.	
  

Both	
  the	
  initiation	
  request	
  and	
  the	
  data	
  retrieval	
  request	
  must	
  include	
  the	
  access	
  token	
  in	
  the	
  HTTP	
  
header.	
  The	
  request	
  must	
  be	
  sent	
  over	
  an	
  HTTPS	
  connection	
  using	
  the	
  POST	
  method,	
  where:	
  
       •       Authorization	
  MUST	
  be	
  included:	
  bearer	
  1234567890ABCDEF	
  
       •       Content	
  type	
  MUST	
  be:	
  “application/json;charset=UTF-­‐8”	
  
       •       Request	
  content	
  MUST	
  be	
  encoded	
  as	
  a	
  JSON	
  object.	
  
	
  
©	
  2014	
  AT&T	
  intellectual	
  property.	
  all	
  rights	
  reserved.	
  AT&T,	
  the	
  AT&T	
  logo	
             Effective	
  Date:	
  14	
  August	
  2014	
  
and	
  all	
  other	
  AT&T	
  marks	
  contained	
  herein	
  are	
  trademarks	
  of	
  AT&T	
  
                                                                                                                                                       Page	
  10	
  of	
  63
intellectual	
  property	
  and/or	
  AT&T	
  affiliated	
  companies	
  
AT&T 	
   V ERIFY	
   C ONNECT	
   ( V 3.0) 	
   I NTEGRATION	
   G UIDE	
   F OR	
   J AVA S CRIPT	
   L IBRARY	
                               	
  

3.2.1             User	
  Authentication	
  
Use	
  AT&T	
  Verify	
  Connect	
  as	
  a	
  first-­‐factor	
  form	
  of	
  authentication,	
  or	
  enhance	
  an	
  existing	
  implementation	
  
to	
  introduce	
  second-­‐factor	
  or	
  multi-­‐factor	
  authentication.	
  For	
  example:	
  
•           First-­‐factor	
  form	
  of	
  authentication	
  
            AT&T	
  Verify	
  Connect	
  identifies	
  the	
  user	
  before	
  the	
  RP.	
  AT&T	
  Verify	
  Connect	
  requires	
  access	
  to	
  a	
  
            credential	
  verification	
  service	
  and	
  a	
  service	
  to	
  map	
  the	
  credential	
  identifier	
  (card	
  PAN)	
  to	
  the	
  RP’s	
  
            user	
  identifier.	
  
            Currently,	
  only	
  contactless	
  credentials	
  (smartcards)	
  are	
  supported	
  for	
  this	
  form.	
  
•           Second-­‐factor	
  form	
  of	
  authentication	
  
            RP	
  identifies	
  the	
  user	
  and	
  requests	
  that	
  AT&T	
  Verify	
  Connect	
  independently	
  verify	
  the	
  user’s	
  identity.	
  
            Authentication	
  mechanisms	
  can	
  include:	
  
            o     Contactless	
  credential	
  presentation	
  
            o     Phone	
  call	
  or	
  SMS-­‐based	
  message	
  to	
  a	
  registered	
  telephone	
  number	
  
            o     OATH	
  cryptogram	
  generated	
  from	
  a	
  user’s	
  verified	
  device.	
  A	
  verified	
  or	
  “vetted”	
  device	
  is	
  defined	
  
                  by	
  the	
  RP	
  and	
  the	
  RP	
  can	
  provide	
  a	
  credential	
  expiry	
  policy	
  to	
  require	
  the	
  user	
  to	
  periodically	
  re-­‐
                  verify	
  their	
  device(s).	
  
•           Multi-­‐factor	
  form	
  of	
  authentication	
  
            The	
  RP	
  identifies	
  the	
  user	
  and	
  passes	
  this	
  identity	
  to	
  AT&T	
  Verify	
  Connect	
  to	
  verify	
  against	
  the	
  user’s	
  
            registered	
  device(s)	
  to	
  complete	
  the	
  second-­‐factor	
  authentication	
  as	
  described	
  above.	
  

3 . 2 . 1 . 1 I n i t i a t i o n 	
   R e q u e s t 	
  
The	
  endpoint	
  for	
  this	
  request	
  is:	
  https://[Host]/otap-­‐client-­‐manager/init-­‐auth.action	
  
Requests	
  can	
  contain	
  the	
  following	
  data:	
  

    {	
  
    	
            “languge”	
  :	
  “en-­‐CA”	
  
    	
            “actionText”	
  :	
  “Please	
  confirm	
  access”	
  
    	
            “userId”	
  :	
  “user123”	
  
    	
            “configProfile”	
  :	
  “profile1”	
  
    	
            “allowVerification”	
  :	
  “yes”	
  
    }	
  

Request	
  Property	
                          	
                                                Required?	
  

language	
                                                                                       Required	
  

actionText	
                                                                                     Required	
  

userId	
                                                                                         Optional	
  

configProfile	
                                                                                  Optional	
  

context	
                                                                                        Optional	
  

©	
  2014	
  AT&T	
  intellectual	
  property.	
  all	
  rights	
  reserved.	
  AT&T,	
  the	
  AT&T	
  logo	
                Effective	
  Date:	
  14	
  August	
  2014	
  
and	
  all	
  other	
  AT&T	
  marks	
  contained	
  herein	
  are	
  trademarks	
  of	
  AT&T	
  
                                                                                                                                                          Page	
  11	
  of	
  63
intellectual	
  property	
  and/or	
  AT&T	
  affiliated	
  companies	
  
AT&T 	
   V ERIFY	
   C ONNECT	
   ( V 3.0) 	
   I NTEGRATION	
   G UIDE	
   F OR	
   J AVA S CRIPT	
   L IBRARY	
                                     	
  

Request	
  Property	
                         	
                                                 Required?	
  

userIPAddress	
                                                                                  Optional	
  

deviceId	
                                                                                       Optional	
  

sendPush	
                                                                                       Optional	
  

allowVerification	
                                                                              Optional	
  (deprecated	
  as	
  of	
  v2.2)	
  

For	
  a	
  full	
  list	
  of	
  request	
  properties	
  and	
  their	
  descriptions,	
  see	
  Appendix	
  A:	
  Request	
  Properties.	
  

3 . 2 . 1 . 2 I n i t i a t i o n 	
   R e s p o n s e 	
  
Responses	
  can	
  contain	
  the	
  following	
  data:	
  

   {	
  
   	
          “txnId”	
  :	
  “987654321”,	
  
   	
          “widgetCode”	
  :	
  “tGzv3JOkF0XG5Qx2TIKWIA”	
  
   }	
  

Response	
  Property	
                                                                           Required?	
  

txnId	
                                                                                          Required	
  

widgetCode	
                                                                                     Required	
  

error	
                                                                                          Optional	
  

errorDescription	
                                                                               Optional	
  

For	
  a	
  full	
  list	
  of	
  response	
  properties	
  and	
  their	
  descriptions,	
  see	
  Appendix	
  B:	
  Response	
  Properties.	
  
Error	
  codes	
  for	
  this	
  response	
  can	
  include:	
  
           •   invalid_access_token	
  
           •   invalid_request	
  
           •   invalid_request_property	
  
           •   invalid_config_profile	
  
           •   unsupported_language	
  
           •   unknown_user	
  
           •   action_text_required	
  
           •   unsupported_authentication	
  
           •   device_update_required	
  
           •   system_error	
  
           •   plugin_update_required	
  
           •   plugin_update_user_cancelled	
  
               	
  
For	
  a	
  full	
  list	
  of	
  error	
  codes	
  and	
  their	
  descriptions,	
  see	
  Appendix	
  C:	
  Error	
  Codes.	
  

©	
  2014	
  AT&T	
  intellectual	
  property.	
  all	
  rights	
  reserved.	
  AT&T,	
  the	
  AT&T	
  logo	
                    Effective	
  Date:	
  14	
  August	
  2014	
  
and	
  all	
  other	
  AT&T	
  marks	
  contained	
  herein	
  are	
  trademarks	
  of	
  AT&T	
  
                                                                                                                                                              Page	
  12	
  of	
  63
intellectual	
  property	
  and/or	
  AT&T	
  affiliated	
  companies	
  
AT&T 	
   V ERIFY	
   C ONNECT	
   ( V 3.0) 	
   I NTEGRATION	
   G UIDE	
   F OR	
   J AVA S CRIPT	
   L IBRARY	
                                     	
  

3 . 2 . 1 . 3 D a t a 	
   R e t r i e v a l 	
   R e q u e s t 	
  
The	
  application	
  client	
  receives	
  a	
  “completed”	
  notification,	
  after	
  user	
  interactions	
  complete,	
  which	
  is	
  then	
  
passed	
  to	
  the	
  application	
  server	
  to	
  retrieve	
  the	
  resultant	
  data.	
  
The	
  endpoint	
  for	
  this	
  request	
  is:	
  https://[Host]/otap-­‐client-­‐manager/auth-­‐data.action	
  
Requests	
  must	
  contain	
  the	
  following	
  data:	
  

   {	
  
   	
          “txnId”	
  :	
  “987654321”	
  
   }	
  

Request	
  Property	
                                                                            Required?	
  

txnId	
                                                                                          Required	
  

For	
  a	
  full	
  list	
  of	
  request	
  properties	
  and	
  their	
  descriptions,	
  see	
  Appendix	
  A:	
  Request	
  Properties.	
  

3 . 2 . 1 . 4 D a t a 	
   R e t r i e v a l 	
   R e s p o n s e 	
  
Response	
  can	
  contain	
  the	
  following	
  data:	
  

   {	
  
   	
          “userId”	
  :	
  “user123”,	
  
   	
          “verifiedDevice”	
  :	
  true,	
  
   	
          “deviceInfo”	
  :	
  
   	
          {	
  
   	
          	
                “deviceId”	
  :	
  “1234567890”,	
  
   	
          	
                “deviceType”	
  :	
  “Intel	
  IPT”,	
  
   	
          	
                “supportsNFC”	
  :	
  true	
  
   	
          }	
  
   }	
  

Response	
  Property	
                                                                           Required?	
  

userId	
                                                                                         Required	
  

deviceInfo	
                                                                                     Optional/Required	
  

verifiedDevice	
                                                                                 Optional	
  (deprecated	
  as	
  of	
  v2.2)	
  

error	
                                                                                          Optional	
  

errorDescription	
                                                                               Optional	
  

reasonCode	
                                                                                     Optional	
  

warnings	
                                                                                       Optional	
  

For	
  a	
  full	
  list	
  of	
  response	
  properties	
  and	
  their	
  descriptions,	
  see	
  Appendix	
  B:	
  Response	
  Properties.	
  

©	
  2014	
  AT&T	
  intellectual	
  property.	
  all	
  rights	
  reserved.	
  AT&T,	
  the	
  AT&T	
  logo	
                    Effective	
  Date:	
  14	
  August	
  2014	
  
and	
  all	
  other	
  AT&T	
  marks	
  contained	
  herein	
  are	
  trademarks	
  of	
  AT&T	
  
                                                                                                                                                              Page	
  13	
  of	
  63
intellectual	
  property	
  and/or	
  AT&T	
  affiliated	
  companies	
  
AT&T 	
   V ERIFY	
   C ONNECT	
   ( V 3.0) 	
   I NTEGRATION	
   G UIDE	
   F OR	
   J AVA S CRIPT	
   L IBRARY	
                                	
  

Error	
  codes	
  for	
  this	
  response	
  can	
  include:	
  
       •       invalid_access_token	
  
       •       unknown_txn	
  
       •       authentication_failed	
  
       •       unknown_user	
  
       •       user_declined	
  
       •       user_cancelled	
  
       •       device_preempted	
  
       •       user_cancelled_update	
  
       •       system_error	
  
       •       txn_not_complete	
  
       •       no_device	
  
       •       invalid_device	
  
       •       device_update_required	
  
       •       timeout	
  
       •       card_read_error	
  
       •       unrecognized_card_type	
  
       •       invalid_card_data	
  
       •       device_removed	
  
       •       device_network_error	
  

For	
  a	
  full	
  list	
  of	
  error	
  codes	
  and	
  their	
  descriptions,	
  see	
  Appendix	
  C:	
  Error	
  Codes.	
  
	
  
	
                                                             	
  

©	
  2014	
  AT&T	
  intellectual	
  property.	
  all	
  rights	
  reserved.	
  AT&T,	
  the	
  AT&T	
  logo	
               Effective	
  Date:	
  14	
  August	
  2014	
  
and	
  all	
  other	
  AT&T	
  marks	
  contained	
  herein	
  are	
  trademarks	
  of	
  AT&T	
  
                                                                                                                                                         Page	
  14	
  of	
  63
intellectual	
  property	
  and/or	
  AT&T	
  affiliated	
  companies	
  
You can also read
Next slide ... Cancel