ავთენტიფიკაცია და წვდომის არეები

`client_credentials` მარტივი სიტყვებით

თქვენი ინტეგრაცია ჩვეულებრივ მოთხოვნაში გასაღებს არასდროს აგზავნის. ის გასაღებს ერთხელ უგზავნის ტოკენის ენდპოინტს და იღებს ხელმოწერილ წვდომის ტოკენს, რომელსაც 15 წუთში ვადა გასდის. ყოველ რეალურ მოთხოვნას თან ახლავს Authorization: Bearer <access_token>. სერვისები ტოკენს ადგილობრივად, მეხსიერებაში ამოწმებენ, ამიტომ თითო მოთხოვნაზე დამატებითი ქსელური გამოძახება არ ხდება, თავად გასაღები კი თქვენს მხარეს რჩება.

1. POST /api/public/v1/oauth/token Client ID-ითა და საიდუმლოთი: HTTP Basic (clientId:secret) ან ფორმის ველები grant_type=client_credentials, client_id, client_secret.
2. შეინახეთ access_token მაქსიმუმ expires_in წამის განმავლობაში (900).
3. ყველა მოთხოვნას დაურთეთ Authorization: Bearer ….
4. 401-ის მიღებისას, ან როცა ტოკენს ვადა ეწურება, დაუბრუნდით პირველ ნაბიჯს.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs…

განახლების ტოკენი და მომხმარებლის შესვლა არ არსებობს. გასაღები კომპანიას ეკუთვნის და ზუსტად იმ წვდომის არეებით მოქმედებს, რომლებითაც შეიქმნა.

წვდომის არეები

წვდომის არე ერთ შესაძლებლობას ასახელებს. ყოველი ენდპოინტი ერთ წვდომის არეს მოითხოვს; საცნობარო მას ყოველ ოპერაციაზე აჩვენებს, ხოლო ტოკენი, რომელსაც ის არ აქვს, იღებს 403 insufficient_scope პასუხს, სადაც დასახელებულია ნაკლული არე.

მანქანური არეები მხოლოდ ინტეგრაციებისთვის არსებობს: attendance.record როლების რედაქტორში ადამიანს ვერ მიენიჭება, და მისი მინიჭება ნებისმიერ ადმინისტრატორს შეუძლია, ვინც გასაღებებს მართავს. ადამიანური არეები იმ უფლებას იმეორებს, რომელიც ადამიანს შეიძლება ჰქონდეს, და გასაღები მას მხოლოდ იმ შემქმნელისგან იღებს, ვისაც ეს უფლება აქვს, ან სუპერადმინისტრატორისგან. რიცხვი შესაბამისი უფლების იდენტიფიკატორია; ის /me პასუხსა და 403-ის დეტალებში ჩანს.

ადამიანების საკუთარი ტოკენები

ადამიანის HourSquare სესიის ტოკენიც მუშაობს საჯარო API-ზე იმ ოპერაციებისთვის, რომლებსაც მისი საკუთარი უფლებები ფარავს: ვისაც Hub-ში დროის აღრიცხვის ნახვა შეუძლია, მას თავისი ტოკენით GET /time-entries გამოძახებაც შეუძლია, და /me მისთვის "principal": "user" მნიშვნელობას აბრუნებს. სწორედ ამას იყენებს ინტერაქტიული საცნობარო, როცა მას Hub-იდან ხსნით. ყველაფრისთვის, რაც ავტომატიზებულია, შექმენით გასაღები: ის არ არის დამოკიდებული იმაზე, დარჩება თუ არა ადამიანი კომპანიაში, და მისი სია, როტაცია და გაუქმება ერთ ადგილას ხდება.

გაუქმება და როტაცია

გასაღების გაუქმება ახალი ტოკენების გაცემას მაშინვე აჩერებს. გაუქმებამდე გაცემული ტოკენი ვადის გასვლამდე მუშაობს, ამიტომ არსებობს 15 წუთამდე ფანჯარა. თუ საიდუმლო გაჟონა, ეს ფანჯარა აქტიურად ჩათვალეთ და ყველაფერს, რაც მასთან ერთად იყო შენახული, როტაცია გაუკეთეთ.

როტაცია გასაღებს იმავე სახელითა და წვდომის არეებით ახლით ანაცვლებს. ძველი საიდუმლო კიდევ 24 საათი მუშაობს, რათა ახალი შეფერხების გარეშე დანერგოთ; ამის შემდეგ მხოლოდ ახალი გასაღები მიიღება. ძველ გასაღებზე დაყენებული ვადა ახალზეც გადადის.

უსაფრთხოების წესები

• გასაღები ან ტოკენი არასდროს ჩაწეროთ მისამართში ან მოთხოვნის პარამეტრებში. ისინი ლოგებში, პროქსიებსა და ბრაუზერის ისტორიაში ხვდება.
• გასაღები არასდროს ჩააშენოთ ბრაუზერის გვერდში ან მობილურ აპლიკაციაში. საჯარო ენდპოინტები CORS ჰედერებს არ აგზავნის, ამიტომ ბრაუზერიდან გამოძახება განზრახ ვერ ხერხდება; გასაღები საკუთარი სერვერის უკან მოათავსეთ.
• ყოველ ინტეგრაციას მიეცით საკუთარი გასაღები წვდომის არეების უმცირესი საკმარისი ნაკრებით და გასაღების შენიშვნაში ჩაწერეთ, სად ინახება.
• ყველაფერზე, რაც დროებითია, დააყენეთ ვადა, ხოლო როცა გამომძახებელს ფიქსირებული მისამართები აქვს, შეზღუდეთ დაშვებული IP დიაპაზონები.
• ეჭვის შემთხვევაში როტაცია გაუკეთეთ. როტაცია არაფერი ღირს, სანამ ძველი გასაღები 24 საათის განმავლობაში მოქმედებს.
• Hub-ში თვალი ადევნეთ სვეტს „ბოლო გამოყენება“: გასაღები, რომელიც თვეებია არ გამოყენებულა, გასაუქმებელი გასაღებია.

გასაღებებს ამოსაცნობი ფორმა აქვს — hsq_, 8-სიმბოლოიანი იდენტიფიკატორი და საიდუმლო — ამიტომ საიდუმლოებების სკანერი ისე დაკონფიგურირდება, რომ კოდის საცავში მოხვედრილი გასაღები დაიჭიროს.